#Cmdline

Preprocessor directive

Syntax
   #cmdline "args..."

Parameters
   args...
      argument list (separated by spaces) of valid Compiler Options except 
      -print and also generic option -help.

Description
   #cmdline is a pre-processor directive that allows specifying 
   compiler options from inside the first specified fb source file.  The 
   first source file is the first specified '.bas' file given on the shell 
   or IDE command line invoking the fbc compiler.  #cmdline directives 
   specified in the first source file affect all source files subsequently 
   compiled.  #cmdline directives inside source files other than the first 
   source file are ignored.

   #cmdline is only allowed at module scope and can be conditionally 
   processed with #if pre-processor statements.  #cmdline statements must 
   appear before any declarative or executable statements.  Any #cmdline 
   statements after the first declarative or executable statement are 
   ignored.

   #cmdline directives are processed on the first pass of the the first 
   '.bas' source file when they appear in the source file.  If an invalid 
   command line option is given in the #cmdline statment, compilation 
   immediately aborts. #cmdline directives are ignored on the second pass 
   of the source file even if a conditional #if would add something 
   different on the second pass.

   At first fbc initializes as usual and begins parsing the fb source code 
   using the options given from the shell or IDE's fbc ... command line.  
   As #cmdline directives are processed, they are merged into the current 
   compiler configuration.  Depending on the command line options 
   encountered, fbc can continue parsing, restart the parser, or restart 
   fbc (for example: no restart after #cmdline "-mt", restart the parser 
   after #cmdline "-gen gcc", restart the build after #cmdline "-target 
   win64").

   fbc has no clever way to detect when all the #cmdline directives in 
   source have been processed, so there are 2 pseudo command line options 
   to instruct fbc what to next if it is necessary:
      #cmdline "-end"
         option to restart parser or build if needed.
      #cmdline "-restart"
         option to always restart build.
   If neither #cmdline "-end" nor #cmdline "-restart" were encountered, fbc 
   continues processing to the end of the first source file and restarts 
   only if necessary. 

   Adding -z nocmdline in the shell/IDE command line option ignores 
   #cmdline directives completely in source and allows user to override all 
   source directives using the shell/IDE fbc compiler command line only.

   Adding -w all on the shell/IDE command line option allows to get 
   warnings about ignored #cmdline directives.

Example
   Add a simple option in source to set the optimization level for GCC:
   #cmdline "-O 2"

   Print __FB_OPTIMIZE__  '' just to check the optimization level

   Sleep
         

   When #cmdline is not processed (no 'invalid command-line option' error 
   message is reported):
   (fbc parser is active when checking for #cmdline, so it's expected that 
   it follows sames rules as any other source code)
   '' not processed in single line comments
   '#cmdline "asdf"

   '' not processed in multi line comments
   /'
   #cmdline "-asdf"
   '/

   '' not processed in strings
   Print "#cmdline ""-asdf"""

   '' not processed if skipping over a conditional
   #if 0
      #cmdline "-asdf"
   #endif

   '' not processed when defining macros (as long as the macro is not called)
   #macro DOARGS
      #cmdline "-asdf"
   #endmacro

   Sleep
         

   Set options in source based on real fbc ... compiler command line option 
   given:
   (full error checking is activated depending if debug option '-g' was 
   given on the fbc ... compiler command line)
   '' '-g' command line option given on the real ##//fbc ...//## compiler command line?

   #if __FB_DEBUG__
      #cmdline "-exx -w pedantic -w constness"
   #endif
         

   Define a global symbol for all modules, starting with two modules: 
   main.bas and tools.bas, and compile both with the single '$ fbc 
   main.bas' compiler command line:
   (this is different than #include tools.bas in main.bas because the two 
   modules are compiled separately then linked)
   '' main.bas
   ''
   '' compile with:
   ''   $ fbc main.bas
   ''
   '' and will be same as if we did:
   ''   $ fbc main.bas tools.bas -d DoTrickyStuff

   '' add the tools module
   #cmdline "-b tools.bas"  '' or: #cmdline "tools.bas"

   '' gobal #define for all modules
   #cmdline "-d DoTrickyStuff"

   Declare Function IsTrickyTools() As Boolean

   #ifdef DoTrickyStuff
   Print "DoTrickyStuff is defined in the main.bas module"
   #endif

   If IsTrickyTools() Then
   Print "DoTrickyStuff is defined in the tools.bas module"
   End If

   Sleep
         

   '' tools.bas
   ''

   Function IsTrickyTools() As Boolean
      #ifdef DoTrickyStuff
      Return True
      #else
        Return False
      #endif
   End Function
         

Version
   * Since fbc 1.09.0

Differences from QB
   * New to FreeBASIC

See also
   * fbc command-line
   * Compiler Options
   * Intrinsic Defines

