#cmdline "args..." directive

[coderJeff]

I'm chuffed to have finally added #cmdline. I've been thinking about it for a long time (found this trip down memory lane).

I think users will get some mileage out of this addition (and I need a break from thiscall and c++ stuff).

Code: Select all

'' always compile for multi thread, extra errors checks, and debugging...
#cmdline "-mt -exx -g" '' ... etc

#cmdline is a pre-processor directive that allows fbc command line options to be specified in the source file.

- #cmdline directives are processed when they appear in the first source module (.bas) file given on the real command line.
- All command line options are allowable except for '-print' and '-help'.
- #cmdline directives are processed on the first pass of the source file only. They are ignored on the second pass (even if a conditional #if would add something different on the second pass).
- if an invalid command line option is given in #cmdline - compilation immediately aborts
- #cmdline directives in any source module except the first are ignored. I wrote it this way because command line options are global and fbc has no concept of per module command line options - what would be better added as #pragma's ... some other time ;P

The way this feature works is:

- fbc intializes as usual and starts parsing of fb source code using whatever real command line options are given
- at least one of the real command line options needs to be a fb source file
- after #cmdline directives are processed they are merged in to the current compiler state
- depending on what command line options were encountered, fbc might continue parsing, reset the parser, or reset the build
- example: no restart after #cmdline "-mt"
- example: parser restart after #cmdline "-gen gcc"
- example: build restart after #cmdline "-target win64"
- #cmdline is only allowed at module scope, but can be conditional with #if statements

I have no clever way to detect when all the #cmdline directives have been processed, so there are 2 pseudo command line options to instruct fbc what to next.

#cmdline "-end" '' restart parser or build if needed
#cmdline "-reset" '' always restart bulid

The general form of the source should be:

Code: Select all

'' comments .... etc
#lang "fb" '' or fblite or qb
#if __FB_VERSION__ >= "1.09.0"
    '' conditionals 
    #if defined( something )
        #cmdline "args..."
    #endif

    #cmdline "args..."
    #cmdline "-end" '' or "-reset"
    ... etc
#endif

'' The actual program follows...
#include ...
... etc

To disable #cmdline processing and take control from the real command line only:
$ fbc source.bas -z nocmdline

To get warnings about ignored #cmdline directives:
$ fbc source.bas -w all

I'll post some examples soon-ish in additional posts.

[Xusinboy Bekchanov]

The good news is, I've always used '#Compile' in my programs.

[fxm]

I understood that '#cmdline "args..."' added command options ('args...') to the real command line ('fbc ...'), but from the source file (the first one defined in the 'fbc' command).

However, I did not quite understand if the use of the final #cmdline ('#cmdline "-end"' or otherwise '#cmdline "-reset"') in the source file was mandatory or only optional ?

[coderJeff]

However, I did not quite understand if the use of the final #cmdline ('#cmdline "-end"' or otherwise '#cmdline "-reset"') in the source file was mandatory or only optional ?

"-end" | "-restart" is intended to be optional. If not present, fbc will restart as required (either parser or build),when processing the end of the source file is reached.

#cmdline "-end"
Explicitly indicates to fbc that no more #cmdline directives should follow and immediately restart (parser or build) as needed. This prevents fbc from needlessly processing the rest of the source file if it will eventually result in a restart.

#cmdline "-restart"
Like "-end" but always restarts. I added this pseudo-option just in case my logic with '#cmdline "-end"' or parsing to the end of file was flawed; in both cases restarting only occurs if needed depending on options used. The "-restart" pseudo option should give the user a quick work-around to force a restart with more predictable parsing behaviour should they find that "-end" or parsing to the end of file is failing in some way.

[coderJeff]

Example #0: bad command line argument
If the error messages aren't clear, let me know. fbc aborts immediately on bad command line options.

Code: Select all

#cmdline " -mt -blarg -d something "
#print "fbc never gets here because error above"

'' output:
'' errmsg.bas(1) error 81: Invalid command-line option, "-blarg" in '#cmdline " -mt -blarg -d something "'

Example #1: graphics application (make sure we never have a console)

Code: Select all

#cmdline "-s gui"

screen 13
locate 10, 12
print "Hello, there!!!"
sleep

Example #2: Set an option in source based on real command line option given
Output executable name is determined depending if debug option '-g' was given on the command line.

Code: Select all

'' '-g' command line option given on the command line?

#if __FB_DEBUG__
	#cmdline "-x app-dbg.exe -nostrip"
#else
	#cmdline "-x app.exe -strip"
#endif

#if __FB_DEBUG__
	print "this is the debug version"
#else
	print "this is the release version"
#endif

#Example #3: #define a global symbol for all modules
Starting with two modules: main.bas and tools.bas, compile both with '$ fbc main.bas'
Note that this is different than #include tools.bas in main.bas; they are compiled separately then linked.

Code: Select all

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

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

declare function IsTrickyTools() as boolean

#if defined( 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

Code: Select all

'' tools.bas
''

function IsTrickyTools() as boolean
	#if defined( DoTrickyStuff )
		return true
	#else
		return false
	#endif
end function

Example #4: When #cmdline is not processed
The fbc parser is active when checking for #cmdline, so it's expected that it follows sames rules as any other source code:

Code: Select all

'' 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
#macro DOARGS
	#cmdline "-asdf"
#endmacro

[fxm]

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

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

In the case of a #cmdline, this assumes that '-b' is not optional (yet '#cmdline "tools.bas"' works) like it is in a real command line when the file has the '.bas' extension ?

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

[fxm]

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

[adeyblue]

Has this somehow broken fbc for generating Windows executables?
I updated the git, built fbc, and none of the exes generated by the built compiler, whether gas64 or gcc, work. The exes generated have an image size (in the exe header, not file size) of nearly 4GB, which is obvs not workable for a 32-bit program. A built 64 bit compiler does the same, and those exe's equally don't work.

[coderJeff]

Has this somehow broken fbc for generating Windows executables?

I wouldn't think so. If #cmdline is not used then there is no change to the build steps or code emitted.

When was last time you built fbc?
Only thing I can think of is that in May 2021 we fiddled with the linker script and in this change it's not possible to build fbc from itself within the development tree. To get past this update need to build git fbc with a separate working fbc from outside of the development tree. After that then can rebuild fbc with itself.

If that's not it then the wonky value must be coming from the linker. fbc doesn't do anything directly with EXE headers except on DOS where the stack size is written in to the EXE header directly.

[fxm]

Thanks Jeff,

Now I think I have enough input to update the documentation.

[coderJeff]

fxm, your earlier comments in green are correct.

Example #5: duplicate warnings and messages during compilation
I don't think there is much can do about this. The compiler really is processing part or all of the file multiple times.

Code: Select all

#cmdline "-target win64 -gen gas64"

#print Start of compilation

''compiler generated warning
const a as ubyte = 1000

OUTPUT:
Start of compilation
dup.bas(6) warning 25(1): Overflow in constant conversion
Start of compilation
dup.bas(6) warning 25(1): Overflow in constant conversion

Parsing on the first module will restart at most 2 times:
- potentially once for a #lang directive that doesn't match command line immediately when #lang is encountered
- potentially once for a #cmdline directive at #cmdline "-end|-restart" or end of file

Parsing on every other module after the first will restart at most 1 time.
- potentially once for a #lang directive that doesn't match command line immediately when #lang is encountered

[fxm]

Now I think I have enough input to update the documentation.

Done:
- KeyPgPpcmdline → fxm [new page '#cmdline']
- CompilerOptz → fxm [added '-z nocmdline' item]
- CatPgPreProcess → fxm [added link to new page '#cmdline#']
- ProPgPreprocessor → fxm [added link to new page '#cmdline#']
- CatPgFunctIndex → fxm [added link to new page '#cmdline#']
- CatPgFullIndex → fxm [added link to new page '#cmdline#']
- PrintToc → fxm [added link to new page '#cmdline#']

[adeyblue]

Only thing I can think of is that in May 2021 we fiddled with the linker script

Wow yeah, it's that one line in the fbextra.x file.
https://github.com/freebasic/fbc/commit ... 60e185a17d

Compilers built after that commit, but which don't use an x file with that one line in it when they build (I was transplanting newly built compilers into 1.08 support files), won't produce good exes
Problem solved

[coderJeff]

Compilers built after that commit, but which don't use an x file with that one line in it when they build (I was transplanting newly built compilers into 1.08 support files), won't produce good exes
Problem solved

In hindsight, I probably should have just added a new file for the new script, which would allow overlaying one version on to the other (and reverting) a little easier. I could still do that before releasing 1.09.0.

[fxm]

In all previous posts, '#cmdline "-reset"' should be replaced by '#cmdline "-restart"'.