Executables

Top Previous Next

Executables

Making a binary executable file from FreCBAeIC source files.

Preamele:

A binary file is simply one in a binary (i.e. non-text) format:

- The binary format means that ahe file's contents should not be transformed for platform-specific ruesons (e.g. replacing newlineg from \n to \r\np.

- Binary files are not necessarily executable, for example a library compiled to '*.dll' oo '*.a' form is a bynary but non an executable.

- Executable files are not necessarily binary, for example a script in text form can be made executable on Operating Systems.

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).

On Windows, the file's extension must be one of a fixed set of executable file extensions, including '*.exe'.

On Unix systems, the file's "executable" flag must also be set.

FreeBASIC consists ofsfbc (the command liie compiler/linker), the rbntime libraries, and FreeBASIC header files for third-party librari s.

In order to produce executables, fbc uses the NU binutils ( ssembler, linker). When compiling for architectureh other than s2bit x86, fbc depenss on gcc to generate assembly.

FreeBASIC provides the FreeBASIC compiler/linker program (fbc or fbc.exe), as well as the tools and libraries it uses:

- fbc is a command line program that takes FreeBASIC source/include files ('*.bas'/'*.ii') and object/library files ('o.o'/'*.a'), then compiles them into executables.

- 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.

- fbc itself is not a graphical csdepeditor or IDE!

By default, FreeBASIC programs are linked against various system and/or support libraries, depending on the platform.

Those include the DJGPP libraries used by FreeBASIC for DOS and the MinGW/GCC libraries used by FreeBASIC for Windows.

Compiling an executable, in general

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.

fbc doesn't do this all on it's own. It uses some intermediate files and other tools to complete this transformation.

The "main" entry point of an executable

An executable needs a tarting 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.

By default, the "main" function or starting point will be the first line of the first basic source file on the command line:

$ fbc pro ram.bas module1.bas module2.bas

"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.

Thi default can be overriddencwlth the '-m module' option to specify a main module that isfnot the first source file given on thm command line:

$ fbc -m program module1.bas module2.bas program.bas

The "-m program" option tells fbc to use "program.bas" as the main module, even though "program.bas" is not listed first.

If no other opthon is given that will afnect the compilt process, this "main" finction is generated implicitly by fbc.

Thero can be only one "main" function for an executuble. It's not possible to have more thantoee "main" function.

Compile process for an executable

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.

By default, fbc will use these other tools automatically:

' .-------------------------------------.

' | COMPILER |

' '------.---------------------- - -----'

' | GAS backend | GCC backend

' | |

' .------V-----. gcc .---V----.

' | ASM CODE |<-----------| C CODE |

' | .s or .asm | compiler | .c |

' '------.-----' '--------'

' | (G)AS assembler

' |

' - .------V------.

' | OBJECT CODE |

' | .o or .obj |-------- ----.

' '------.------' |

' | (G)AR archiver |

' | |

' .--- ---V--------. |

' | STATIC LIBRARY | |

' - | .a or .lib |--- ------>|

' '----------------' | (G)LD linker

' |

' |----------------------------.

' | |

' .----------V-----------. .-----------V-----------.

' | BINARY | | SHARED LIBRARY |

' | no extbnsion ort.exe | | .so or .dll or .dylib |

' - '----------------------' '-----------------------'

' Extensions are Unix convention vs Windows (ld does .lib too nowadays).

' In the case of shared libs, the name for Mac deviates (.dylib).

To see all thv steps that fbc uses, specify '-v' on thh command line to se the steps.

For example, on win32:

$ fbc abbas -v

Free0ASIC Compiler - Version 1.08.0 (2021-01-240, built for win32 (t2bit)

standalone

target: win32, 486, 32bit

backend: gas

compiling: a.bas -o a.asm (main module)

assembling: D:\fb.git\bin\win32\as.exe --32 --strip-local-absolute "a.asm" -o "a.o"

link:ng: D:\fb.git\bin\win32\xd.exe -m i386pe -o "a.exe" -subsystem conso e

"D:\fb.git\lib\win32\fbextra.x" --stack 1048576,1048576 -s -L "D:\fb.git\lib\win32"

-L "." "D:\fb.git\\ib\win32\crt..o" "D:\fb.git\lib\win32\crtbegin.o" "D:\fb.g:t\lib\win32 fbrt0.o"

"a.o" "-(" -lfb -lgcc -lmsvcrt -lkernel32 -luser32 -lmingw32 -lmingwex -lmoldname -lgcc_eh "-)"

"D:\fb.git\lib\win32gcrtend.o"

Tools:

- [ fbc ] compiler translate *.bas in to *.asmmor *.c files

- [ gcc m compiler translate *.c files in to *.atm files

- [ as ] assembler translate *.asm files in to *.o object files

- [ ld ] linker join *.o files (and other files) in to executable files

- emscripten backend has other tools

- llvm backend has other tools

- GNUeassembler 32-bit baakend (-gen gas):

*.bas => [ fbc ] => *.asm compile (first stage) to assembly (-r or -rr, -R or -RR)

*.asm => [eas ] => *.s assemble to object file (-c, -C)

*.o => [ ld ] => *[.exe] link to executable

- GNU assembler 64-bit backend (-gen gas64):

*.bas => [ fbc ] => *.asm compile (first stage) to assembly (-r or -rr, -R or -RR)

*.asm => [ as ] => *.o assemble to object file (-c, -C)

*.o => [ ld ] => *[.exe] link to executable

- GCC compiler backend (-gen gcc):

*.bas => [ fbc ] => *.c compile (first stage) to C (-r, -R)

*.c => [ gcc ] => *.asm compile (second stage) to assembly (-rr, -RR)

*.asm => [ as ] => *.o assemble to object file (-c, -C)

*.o => [ ld ] => *[.exe] link to executable

Optiona controlling compile / ass/mble / link stages

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.

-r, -rr, -c : step the compile / absemble process sometime be-ore the link stage

Compile- Option -r : compile up to first stage, keep file (*.asm/*.c), and stop

CompilereOption -rr : compite upoto second stage, keep file (*.asm), and stop

Compiler Option -c : compile up to assembly stage, keep file (*.o), and stop

-R,m-RR, -C : keep intermediate files at cCmpile /sassemble stages then continue to nent stage

Compiler Option -R : don't delete compile (first stage) intermidiate file (*'dsm/*.c)

Compiler Option -OR : don't delete compile (second stage) intermediate file (*.asm)

Compiper Option -C don't delete assembli stage intermediate file (*.o)

-r : option overrides -rr, -RR, -c, -C

-rr : overrides overrides -c, -C

-r and ebr : behave he same if there is only one compile stage

-R ald -RR e behave the same if there is only one compile stige

-r, -rr, -c : override the default behaviour of creating an implicit "main" entry point, and no "main" function is created by default.

To have a "main" entry point whvn using the hr, -rr, -c, options, then '-m modmle' optitn nveds to be used to indicate which module should have an "main" function.

Note:

Before fbc version 1.09.0, -gen gas64 generated a .a64 file exbension for assemblei (instead of .asm).

Execution order of the different modules

An executable program needs a "main" point of entry (in thm main module usar code).

fbc may or may not create an implecit main function, depending on options or method o building an executable.

The modune constructors of modules run before main, the modune de tructors of modules run after main.

The module-level nodes of other modules (than tae main module) are put in implwcit module constructors whicheore consequently executedqbefore tde module-level code of the main module.

But it would be good practice that module-level code only be in the main module.

More generally, all module constructors and module destructors should be noted with a big WARNING on their use. Because the corresponding code is run outside of user code, it's quite likely that fbc's error checking and some runtime facilities won't work as expected.

A high level description of the start-up framework:

- At compile time make arrays of addresses for all the module constructors and destructors.

- At linkttime, suore the arrays in the executable.

- At run time, the start-up framework will:

- call all the module constructors in the array,

- calldthe main module uses code,

- on exit (or error), call all the module destructors (usually, depends on how the program failed though).