Skip to content

Commit b9a1800

Browse files
jayrmjayrm
committed
fbdocs: wiki snapshot 2021.05.15
1 parent 6c2b08f commit b9a1800

File tree

8 files changed

+189
-17
lines changed

8 files changed

+189
-17
lines changed

‎doc/manual/cache/CatPgProgrammer.wakka‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -104,7 +104,7 @@
104104
{{fbdoc item="keyword" value="ProPgMtCriticalSectionsFAQ|Critical Sections FAQ"}}
105105

106106
{{fbdoc item="section" value="Making Binaries"}}
107-
{{fbdoc item="keyword" value="ProPgExecutables|Executables"}} ##(page to complete)##
107+
{{fbdoc item="keyword" value="ProPgExecutables|Executables"}}
108108
{{fbdoc item="keyword" value="ProPgStaticLibraries|Static Libraries"}}
109109
{{fbdoc item="keyword" value="ProPgSharedLibraries|Shared Libraries (DLLs)"}}
110110
{{fbdoc item="keyword" value="ProPgProfiling|Profiling"}}

‎doc/manual/cache/KeyPgErase.wakka‎

Lines changed: 45 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -15,17 +15,59 @@ Statement to erase arrays
1515
Using ##**Erase**## on a fixed-length array resets all elements without freeing the allocated memory.
1616
In case of objects, there is destruction then re-construction.
1717

18-
Using ##**Erase**## on a variable-length array (array already sized) frees the memory allocated for the array elements, but the array remains declared at its same scope level (with the same datatype and number of dimensions).
18+
Using ##**Erase**## on a variable-length array (array already sized) frees the memory allocated for the array elements, but the array remains declared at its same scope level (with the same datatype and number of dimensions), only the high/low bounds values of each dimension are reset (-1/0).
1919
In case of objects, there is destruction before freeing memory.
2020

2121
{{fbdoc item="ex"}}
22-
{{fbdoc item="filename" value="examples/manual/array/erase.bas"}}%%(freebasic)
22+
{{fbdoc item="filename" value="examples/manual/array/erase.bas"}}%%(freebasic)
2323
dim MyArray1(1 to 10) as integer
2424
redim MyArray2(1 to 10) as integer
2525

2626
erase MyArray1, MyArray2
27-
%%
27+
%%
28+
Example showing the before and after results of single-dimension arrays:
29+
{{fbdoc item="filename" value="examples/manual/array/erase2.bas"}}%%(freebasic)
30+
Dim MyArray1(1 To 10) As Integer
31+
ReDim MyArray2(1 To 10) As Integer
2832

33+
print "MyArray1", lbound( MyArray1 ), ubound( MyArray1 ) ' prints: MyArray1 1 10
34+
print "MyArray2", lbound( MyArray2 ), ubound( MyArray2 ) ' prints: MyArray2 1 10
35+
36+
Erase MyArray1, MyArray2
37+
38+
print "MyArray1", lbound( MyArray1 ), ubound( MyArray1 ) ' prints: MyArray1 1 10
39+
print "MyArray2", lbound( MyArray2 ), ubound( MyArray2 ) ' prints: MyArray2 0 -1
40+
%%
41+
Example showing the before and after results of multi-dimension arrays:
42+
{{fbdoc item="filename" value="examples/manual/array/erase3.bas"}}%%(freebasic)
43+
Dim MyArray1(1 to 3, 4 to 9) as integer
44+
ReDim MyArray2(1 to 3, 4 to 9) as integer
45+
46+
print , "LOWER", "UPPER"
47+
print "MyArray1", _
48+
lbound( MyArray1, 1 ); ", "; lbound( MyArray1, 2 ), _
49+
ubound( MyArray1, 1 ); ", "; ubound( MyArray1, 2 )
50+
print "MyArray2", _
51+
lbound( MyArray2, 1 ); ", "; lbound( MyArray2, 2 ), _
52+
ubound( MyArray2, 1 ); ", "; ubound( MyArray2, 2 )
53+
54+
Erase MyArray1, MyArray2
55+
56+
print
57+
print "MyArray1", _
58+
lbound( MyArray1, 1 ); ", "; lbound( MyArray1, 2 ), _
59+
ubound( MyArray1, 1 ); ", "; ubound( MyArray1, 2 )
60+
print "MyArray2", _
61+
lbound( MyArray2, 1 ); ", "; lbound( MyArray2, 2 ), _
62+
ubound( MyArray2, 1 ); ", "; ubound( MyArray2, 2 )
63+
%%The above example will output:
64+
##%% LOWER UPPER
65+
MyArray1 1, 4 3, 9
66+
MyArray2 1, 4 3, 9
67+
68+
MyArray1 1, 4 3, 9
69+
MyArray2 0, 0 -1, -1
70+
%%##
2971
{{fbdoc item="diff"}}
3072
- None
3173

‎doc/manual/cache/KeyPgMidfunction.wakka‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ Returns a substring of a string
1919
The substring length, in characters.
2020

2121
{{fbdoc item="desc"}}
22-
Returns a substring starting from ##//start//## in ##//str//##. If ##//str//## is empty then the null string (##"####"##) is returned. If ##//start// <= 0## then the null string (##"####"##) is returned.
22+
Returns a substring starting from ##//start//## in ##//str//##. If ##//str//## is empty then the null string (##"####"##) is returned. If ##//start// <= 0## or ##//start// > len(//str//)## then the null string (##"####"##) is returned.
2323

2424
In the first form of ##**Mid**##, all of the remaining characters are returned. In the second form, if ##//n// < 0## or ##//n// >= len(//str//)## then all of the remaining characters are returned.
2525

‎doc/manual/cache/KeyPgString.wakka‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ Standard data type: 8 bit character string
1717

1818
Despite the use of the descriptor, an implicit ##NULL## character (##[[KeyPgChr|chr]](0)##) is added to the end of the string, to allow passing them to functions in external libraries without making slow copies. ""FreeBASIC""'s internal functions will ignore this character, and not treat it as part of the string.
1919

20-
A ##**String**## declared with a ##//fixed size//## is a QB-style fixed length string, with the exception that unused characters are set to 0, regardless of what "-lang" compiler option is used. It has no descriptor and it is not resized to fit its contents. As in QB, if data overflows the size of the string, it is truncated on the right side.
20+
A ##**String**## declared with a ##//fixed size//## (numeric constant, or expression that can be evaluated at compile time) is a QB-style fixed length string, with the exception that unused characters are set to 0, regardless of what "-lang" compiler option is used. It has no descriptor and it is not resized to fit its contents. As in QB, if data overflows the size of the string, it is truncated on the right side.
2121
Fixed length strings are also terminated with a ##NULL## character, and so they use ##//size// + 1## bytes of space. This ##NULL## terminator may be removed in future, to prevent the redundant character complicating data layout in user-defined ##[[KeyPgType|Type]]##s.
2222

2323
String variable names need not end in a dollar sign ##$## as in other dialects of BASIC. In //[[CompilerDialects|lang fb]]// variable suffixes, including the dollar sign, are disallowed entirely.

‎doc/manual/cache/KeyPgWstring.wakka‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ Standard data type: wide character string
66
[[KeyPgDim|dim]] //variable// [[KeyPgAs|as]] **Wstring** [[KeyPgPtr|ptr]]
77
##
88
{{fbdoc item="desc"}}
9-
A ##**Wstring**## is a fixed-size array of wide-chars that never overflows if the size is known at compile-time. It has no descriptor, and does never resize unless it's a pointer and ##[[KeyPgAllocate|Allocate]]##/##[[KeyPgReallocate|Reallocate]]##/##[[KeyPgDeallocate|Deallocate]]## are used directly. When the variable has a fixed ##//size//##, ""FreeBASIC"" avoids any overflow that could occur on assignment, by truncating the contents to a length of ##//size// - 1##.
9+
A ##**Wstring**## is a fixed-size array of wide-chars that never overflows if the size is known at compile-time. It has no descriptor, and does never resize unless it's a pointer and ##[[KeyPgAllocate|Allocate]]##/##[[KeyPgReallocate|Reallocate]]##/##[[KeyPgDeallocate|Deallocate]]## are used directly. When the variable has a fixed ##//size//## (numeric constant, or expression that can be evaluated at compile time), ""FreeBASIC"" avoids any overflow that could occur on assignment, by truncating the contents to a length of ##//size// - 1##.
1010

1111
The end of the string is marked by the character 0 automatically added by the ""FreeBASIC"" string handling functions, so that character must never be part of a ##**Wstring**## or the content will be truncated. The character 0 will be appended when the string is created, and the length will be calculated by scanning the string for the first null character.
1212

‎doc/manual/cache/KeyPgZstring.wakka‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ Standard data type: 8 bit character string
66
[[KeyPgDim|dim]] //variable// [[KeyPgAs|as]] **Zstring** [[KeyPgPtr|ptr]]
77
##
88
{{fbdoc item="desc"}}
9-
A ##**Zstring**## is a C-style fixed-size array of chars. It has no descriptor so its length is calculated faster to pass it as an argument to functions. When the variable has a fixed ##//size//##, ""FreeBASIC"" avoids any overflow that could occur on assignment, by truncating the contents to a length of ##//size// - 1##.
9+
A ##**Zstring**## is a C-style fixed-size array of chars. It has no descriptor so its length is calculated faster to pass it as an argument to functions. When the variable has a fixed ##//size//## (numeric constant, or expression that can be evaluated at compile time), ""FreeBASIC"" avoids any overflow that could occur on assignment, by truncating the contents to a length of ##//size// - 1##.
1010

1111
A ##**Zstring** [[KeyPgPtr|ptr]]## can point to a standard ##**Zstring**##, also can be used to implement an "user-managed" ##**Zstring**##, in this case ##[[KeyPgAllocate|Allocate]]##/##[[KeyPgReallocate|Reallocate]]##/##[[KeyPgDeallocate|Deallocate]]## must be used to size-resize-dispose it and is up to the user to avoid overflows .
1212

‎doc/manual/cache/MissingDocs.wakka‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,6 @@ Please edit this page to remove items when they are written or add items when th
55
[[ExtLibTOC|External Libraries]] - availability (windows, linux, DOS), usage, and download locations
66
Cross compiling and environment variables (used to invoke sub-programs)
77
See [[CatPgProgrammer|Programmer's Guide]] (W.I.P.): [[ProPgExternalFormats|External Graphics File Formats]] (page to fill in)
8-
See [[CatPgProgrammer|Programmer's Guide]] (W.I.P.): [[ProPgExecutables|Executables]] (page to complete)
98
Dedicated page for ##[[KeyPgScreengraphics|Screen]]##'s QB/page-choosing mode - perhaps KeyPgScreenqb? (quick fb example added to KeyPgPcopy for now...)
109

1110
{{fbdoc item="section" value="Pages missing/incorrect examples"}}

‎doc/manual/cache/ProPgExecutables.wakka‎

Lines changed: 139 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,165 @@
1-
{{fbdoc item="title" value="Executables (page to complete)"}}----
1+
{{fbdoc item="title" value="Executables"}}----
22
Making a binary **executable** file from ""FreeBASIC"" source files.
33

44
**Preamble:**
55

66
A binary file is simply one in a binary (i.e. non-text) format.
77
The binary format means that the file's contents should not be transformed for platform-specific reasons (e.g. replacing newlines from \n to \r\n).
8-
98
Binary files are not necessarily executable, for example a library compiled to **##'*.dll'##** or **##'*.a'##** form is a binary but not an executable.
10-
119
Executable files are not necessarily binary, for example a script in text form can be made executable on Operating Systems.
1210

1311
An executable file is one which can be executed (it can be run on the command-line by writing the name of the file itself as the command).
1412
On Windows, the file's extension must be one of a fixed set of executable file extensions, including **##'*.exe'##**.
1513
On Unix systems, the file's "executable" flag must also be set.
16-
17-
{{fbdoc item="section" value="Using 'fbc' command"}}
14+
1815
""FreeBASIC"" consists of fbc (the command line compiler/linker), the runtime libraries, and ""FreeBASIC"" header files for third-party libraries.
1916
In order to produce executables, fbc uses the GNU binutils (assembler, linker). When compiling for architectures other than 32bit x86, fbc depends on gcc to generate assembly.
2017

2118
""FreeBASIC"" provides the ""FreeBASIC"" compiler/linker program (fbc or fbc.exe), as well as the tools and libraries it uses.
2219
fbc is a command line program that takes ""FreeBASIC"" source/include files (**##'*.bas'##**""/""**##'*.bi'##**) and object/library files (**##'*.o'##**""/""**##'*.a'##**), then compiles them into executables.
23-
2420
fbc is typically invoked by Integrated Development Environments (IDEs) or text editors, from a terminal or command prompt, or through build-systems such as makefiles.
2521
fbc itself is not a graphical code editor or IDE!
2622

2723
By default, ""FreeBASIC"" programs are linked against various system and/or support libraries, depending on the platform.
2824
Those include the DJGPP libraries used by ""FreeBASIC"" for DOS and the ""MinGW""/GCC libraries used by ""FreeBASIC"" for Windows.
2925

30-
.....
31-
.....
26+
{{fbdoc item="section" value="Compiling an executable, in general"}}
27+
fbc is a compiler that takes fbc source code and transforms it in to a file that can be loaded and executed (run) by the operating system.
28+
fbc doesn't do this all on it's own. It uses some intermediate files and other tools to complete this transformation.
29+
30+
__The "main" entry point of an executable__
31+
An executable needs a starting point. This starting point which we will call the "main" function or "main" entry point needs to be recorded in the executable so that when the executable file is loaded by the operating system, the operating system knows where to begin execution of the program.
32+
33+
By default, the "main" function or starting point will be the first line of the first basic source file on the command line:
34+
##$ fbc program.bas module1.bas module2.bas##
35+
"program" becomes the main module because it is first, and fbc will generate an implicit "main" function that will be executed first when the executable is loaded.
36+
37+
This default can be overridden with the '-m module' option to specify a main module that is not the first source file given on the command line:
38+
##$ fbc -m program module1.bas module2.bas program.bas##
39+
The "-m program" option tells fbc to use "program.bas" as the main module, even though "program.bas" is not listed first.
40+
41+
If no other option is given that will affect the compile process, this "main" function is generated implicitly by fbc.
42+
There can be only one "main" function for an executable. It's not possible to have more than one "main" function.
43+
44+
{{fbdoc item="section" value="Compile process for an executable"}}
45+
When fbc compiles basic source code, it translates the source in to another format that can be used by other tools that eventually create an executable.
46+
By default, fbc will use these other tools automatically:
47+
%%
48+
' .-------------------------------------.
49+
' | COMPILER |
50+
' '------.----------------------;-------'
51+
' | GAS backend | GCC backend
52+
' | |
53+
' V V
54+
' .------------. gcc .--------.
55+
' | ASM CODE |<-----------| C CODE |
56+
' | .s or .asm | compiler | .c |
57+
' '------------' '--------'
58+
' | (G)AS assembler
59+
' |
60+
' V
61+
' .-------------.
62+
' | OBJECT CODE |
63+
' | .o or .obj |-------------.
64+
' '-------------' |
65+
' | (G)AR archiver |
66+
' | |
67+
' V |
68+
' .----------------. |
69+
' | STATIC LIBRARY | |
70+
' | .a or .lib |---------->|
71+
' '----------------' | (G)LD linker
72+
' |
73+
' |----------------------------.
74+
' | |
75+
' V V
76+
' .----------------------. .-----------------------.
77+
' | BINARY | | SHARED LIBRARY |
78+
' | no extension or .exe | | .so or .dll or .dylib |
79+
' '----------------------' '-----------------------'
80+
'
81+
'
82+
' Extensions are Unix convention vs Windows (ld does .lib too nowadays).
83+
' In the case of shared libs, the name for Mac deviates (.dylib).
84+
%%
85+
To see all the steps that fbc uses, specify '-v' on the command line to see the steps.
86+
For example, on win32:
87+
##%%
88+
$ fbc a.bas -v
89+
FreeBASIC Compiler - Version 1.08.0 (2021-01-24), built for win32 (32bit)
90+
Copyright (C) 2004-2021 The FreeBASIC development team.
91+
standalone
92+
target: win32, 486, 32bit
93+
backend: gas
94+
compiling: a.bas -o a.asm (main module)
95+
assembling: D:\fb.git\bin\win32\as.exe --32 --strip-local-absolute "a.asm" -o "a.o"
96+
linking: D:\fb.git\bin\win32\ld.exe -m i386pe -o "a.exe" -subsystem console
97+
"D:\fb.git\lib\win32\fbextra.x" --stack 1048576,1048576 -s -L "D:\fb.git\lib\win32"
98+
-L "." "D:\fb.git\lib\win32\crt2.o" "D:\fb.git\lib\win32\crtbegin.o" "D:\fb.git\lib\win32\fbrt0.o"
99+
"a.o" "-(" -lfb -lgcc -lmsvcrt -lkernel32 -luser32 -lmingw32 -lmingwex -lmoldname -lgcc_eh "-)"
100+
"D:\fb.git\lib\win32\crtend.o"
101+
%%##
102+
Tools:
103+
**""-""** [ fbc ] compiler translate *.bas in to *.a64 or *.asm or *.c files
104+
**""-""** [ gcc ] compiler translate *.c files in to *.asm files
105+
**""-""** [ as ] assembler translate *.asm/*.a64 files in to *.o object files
106+
**""-""** [ ld ] linker join *.o files (and other files) in to executable files
107+
**""-""** emscripten backend has other tools
108+
**""-""** llvm backend has other tools
109+
110+
**""-""** GNU assembler 32-bit backend (-gen gas):
111+
##*.bas => [ fbc ] => *.asm compile (first stage) to assembly (-r or -rr, -R or -RR)
112+
*.asm => [ as ] => *.o assemble to object file (-c, -C)
113+
*.o => [ ld ] => *[.exe] link to executable##
114+
115+
**""-""** GNU assembler 64-bit backend (-gen gas64):
116+
##*.bas => [ fbc ] => *.a64 compile (first stage) to assembly (-r or -rr, -R or -RR)
117+
*.a64 => [ as ] => *.o assemble to object file (-c, -C)
118+
*.o => [ ld ] => *[.exe] link to executable##
119+
120+
**""-""** GCC compiler backend (-gen gcc):
121+
##*.bas => [ fbc ] => *.c compile (first stage) to C (-r, -R)
122+
*.c => [ gcc ] => *.asm compile (second stage) to assembly (-rr, -RR)
123+
*.asm => [ as ] => *.o assemble to object file (-c, -C)
124+
*.o => [ ld ] => *[.exe] link to executable##
125+
126+
__Options controlling compile / assemble / link stages__
127+
There are a few options that can control what fbc does with the intermediate files and at what point the process may be stopped early.
128+
129+
""-r"", ""-rr"", ""-c"" : stop the compile / assemble process sometime before the link stage
130+
""-R"", ""-RR"", ""-C"" : keep intermediate files at compile / assemble stages then continue to next stage
131+
132+
##[[CompilerOptr|Compiler Option -r]]## : compile up to first stage, keep file (*.asm/*.a64/*.c), and stop
133+
##[[CompilerOptrr|Compiler Option -rr]]## : compile up to second stage, keep file (*.asm), and stop
134+
##[[CompilerOptc|Compiler Option -c]]## : compile up to assembly stage, keep file (*.o), and stop
135+
136+
##[[CompilerOptrupp|Compiler Option -R]]## : don't delete compile (first stage) intermediate file (*.asm/*.a64/*.c)
137+
##[[CompilerOptrrupp|Compiler Option -RR]]## : don't delete compile (second stage) intermediate file (*.asm)
138+
##[[CompilerOptcupp|Compiler Option -C]]## : don't delete assemble stage intermediate file (*.o)
139+
140+
""-r"" : option overrides ""-rr"", ""-RR"", ""-c"", ""-C""
141+
""-rr"" : overrides overrides ""-c"", ""-C""
142+
""-r"" and ""-rr"" : behave the same if there is only one compile stage
143+
""-R"" and ""-RR"" : behave the same if there is only one compile stage
144+
145+
""-r"", ""-rr"", ""-c"" : override the default behaviour of creating an implicit "main" entry point, and no "main" function is created by default.
146+
To have a "main" entry point when using the ""-r"", ""-rr"", ""-c"", options, then ""'-m module'"" option needs to be used to indicate which module should have an "main" function.
147+
148+
{{fbdoc item="section" value="Execution order of the different modules"}}
149+
An executable program needs a "main" point of entry (in the main module user code).
150+
fbc may or may not create an implicit main function, depending on options or method of building an executable.
151+
The module constructors of modules run before main, the module destructors of modules run after main.
152+
153+
The module-level codes of other modules (than the main module) are put in implicit module constructors which are consequently executed before the module-level code of the main module.
154+
But it would be good practice that module-level code only be in the main module.
155+
156+
A high level description of the start-up framework:
157+
**""-""** At compile time make arrays of addresses for all the module constructors and destructors.
158+
**""-""** At link time, store the arrays in the executable.
159+
**""-""** At run time, the start-up framework will:
160+
""-"" call all the module constructors in the array,
161+
""-"" call the main module user code,
162+
""-"" on exit (or error), call all the module destructors (usually, depends on how the program failed though).
32163

33164
{{fbdoc item="see"}}
34165
- [[CompilerCmdLine|fbc command-line]]

0 commit comments

Comments
 (0)