Compiler Option: -entry

Forum for discussion about the documentation project.
Post Reply
fxm
Moderator
Posts: 12081
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Compiler Option: -entry

Post by fxm »

@Jeff,

changelog.txt:
Version 1.09.0
[added]
- fbc: add '-entry name' command line option to set program entry point (TeeEmCee)
???
Difference with the '-map < name >' command line ?
SARG
Posts: 1755
Joined: May 27, 2005 7:15
Location: FRANCE

Re: Compiler Option: -entry

Post by SARG »

Map files : plain text files that indicate the relative offsets of functions/variables of a compiled binary.
Entry point : it's a point in a program where the execution of a program begins, and where the program has access to command line arguments.
fxm
Moderator
Posts: 12081
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Compiler Option: -entry

Post by fxm »

SARG wrote:Entry point : it's a point in a program where the execution of a program begins, and where the program has access to command line arguments.
Syntax for specifying the entry point:
a label_name ?
a Sub_name ? (only Public Sub?)
a Function_name ? (only Public Function?)
.....

[edit]
Otherwise I tried to do some tests, but without any success.
SARG
Posts: 1755
Joined: May 27, 2005 7:15
Location: FRANCE

Re: Compiler Option: -entry

Post by SARG »

It seems to replace main() so a sub_name, to be confirmed.

edit : rather a function_name....
Last edited by SARG on Jul 19, 2021 17:12, edited 1 time in total.
fxm
Moderator
Posts: 12081
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Compiler Option: -entry

Post by fxm »

'-entry name':
New command-line to add in the 'Compilation' group or rather in the 'Linking' group ?

Commit found: https://github.com/freebasic/fbc/commit ... f0c7575f3c
fbc: Add -entry commandline option to override the name of the entry
…procedure.

This is necessary in order to use SDL 1.2 or SDL 2.0 on at least Android, OSX,
iOS, and winRT, and is optional on Windows. SDL_main.h #defines main to SDL_main,
and declares the real main() itself. Under FB that can't be done, so the solution
is to pass -entry SDL_main when compiling the main module.

No guarentees that that is all that is needed to properly initialise a
FB program under SDL.

Note: I wasn't sure where to put this global. env.clopt.entry would seem to
be the natural place, but env.clopt contains only integral datatypes,
and file-scope for other structures like fbc seems to be strictly enforced.
So it went into fbc and then passed to fbInit and put in env.
But the use still obscure.
coderJeff
Site Admin
Posts: 4313
Joined: Nov 04, 2005 14:23
Location: Ontario, Canada
Contact:

Re: Compiler Option: -entry

Post by coderJeff »

fxm wrote:'-entry name':
New command-line to add in the 'Compilation' group or rather in the 'Linking' group ?
It's a compilation option.
Give me a few minutes and I'll make some examples to demonstrate internals, not necessarily related to SDL.

Another description could be: '-entry name' specifies the public exported name of the implicit user main function.

The '-entry name' addition is likely not complete and maybe could be done better as a '#pragma' statement or possibly a 'function' attribute.I don't know. Anyway it seemed useful enough to me to include it the addition and explore it's usage. It affects the start-up code and implicit user main, which is also affected by the module being the main module or not.

Relating to the the thread about executables, if this -entry option gets too complicated to explain, then there's probably a better way to handle this. I think the result (some day) is that we want an option that allows specifying an explicit 'main'.

Note: I just realized that '-entry' might be confused with linking options that can also specify the program entry point or entry address to the loader. That's not what this. So maybe this should be '-fbentry name' or '-fbmain name'?

Examples:
To understand what '-entry name' does, first need to understand some internals without it.

main1.bas - simple program - a quick review of the implicit user main.

Code: Select all

'' main1.bas: 
'' - simple program
'' - If compiling and linking in separate steps we need to specify
''   which module is the main module.
''
'' compile: $ fbc -c -m main1 main1.bas
'' link   : $ fbc main1.o
'' OR
'' compile: $ fbc main1.bas

'' ---------------------------------
'' START OF USER'S IMPLICIT MAIN
'' - internally this procedure is named "main" 
'' - a public symbol of "main" is needed to satisfy the linker 
''   and run-time system start-up code

	print "hello"

'' END OF USER'S IMPLICIT MAIN
'' ---------------------------------
main2.bas: - demonstrate the actual internals of the simple program
This should show what fbc generates automatically for start-up code

Code: Select all

'' main2.bas
'' - demonstrate internals of a simple program
'' - we must compile and link in separate steps or give a non-existant
''   module name so that fbc doesn't generate the implicit user main 
''
'' compile: $ fbc -c main2.bas
'' link   : $ fbc main2.o
'' OR
'' compile: $ fbc -m none main2.bas

enum FB_LANG
	FB_LANG_INVALID = -1
	FB_LANG_FB = 0
	FB_LANG_FB_DEPRECATED
	FB_LANG_FB_FBLITE
	FB_LANG_QB
end enum

'' in the fbc compiler the value of FB_LANG is known
'' in source, we need to reconstruct it from __FB_LANG__
#if __FB_LANG__ = "fb"
	const FB_LANG_INDEX = FB_LANG_FB
#elseif __FB_LANG__ = "deprecated"  
	const FB_LANG_INDEX = FB_LANG_DEPRECTATED
#elseif __FB_LANG__ = "fblite"
	const FB_LANG_INDEX = FB_LANG_FBLITE
#elseif __FB_LANG__ = "qb"
	const FB_LANG_INDEX = FB_LANG_QB
#else
	const FB_LANG_INDEX = FB_LANG_INVALID
#endif

'' Implicitly declared by fbc compiler
'' declare sub fb___main cdecl alias "__main" ()
'' declare sub fb_Init alias "fb_Init" ( byval argc as long, byval argv as zstring ptr ptr, byval lang as long )

'' declare function fb_End alias "fb_End" ( byval code as long ) as long
 
'' There must be exactly one "main" in the program
'' fbc implicitly defines "main"
function main cdecl alias "main" _
	( _
		byval argc as long, _
		byval argv as zstring ptr ptr _
	) as long
	'' !!!TODO!!! - dont't assume stack alignment
	'' - need to modify the prolog code
	'' - fbc takes care of this when this is implicitly generated

	'' return value is automatically set to 0 by default, so we don't need this
	'' function = 0

	#if PROFILING
		'' there is no built-in to determine if fbc has profiling enabled
		'' call __monstartup()
	#endif
	
	#ifdef __FB_WIN32__
		fb___main() '' set-up and call global ctors
	#endif

	fb_Init( argc, argv, FB_LANG_INDEX )

	'' all initialization complete, continue with user's 'main'

	'' ---------------------------------
	'' START OF USER'S IMPLICIT MAIN

		print "hello"

	'' END OF USER'S IMPLICIT MAIN
	'' ---------------------------------

	'' return the return code from fb_End()
	fb_End( 0 )

	'' return value is 0 which has already been set by default
	'' but we get a warning here because fbc doesn't know it's already set 
end function
main3.bas: demonstrate the internals, but add the effects of '-entry custom_main'
- slightly simplified from main2.bas for readability

Code: Select all

'' main3.bas
'' - demostrate the internals of a simple program with an alternate entry point
'' - we must compile and link in separate steps or give a non-existant
''   module name so that fbc doesn't generate the implicit user main 
''
'' compile: $ fbc -c main3.bas -entry custom_main
'' link   : $ fbc main3.o
'' OR
'' compile: $ fbc -m none main3.bas -entry custom_main

function custom_main cdecl alias "custom_main" _
	( _
		byval argc as long, _
		byval argv as zstring ptr ptr _
	) as long

	function = 0 '' quiet the warning

	#ifdef __FB_WIN32__	
		fb___main()
	#endif
	fb_Init( argc, argv, 0 )

	'' ---------------------------------
	'' START OF USER'S IMPLICIT MAIN

		print "hello"

	'' END OF USER'S IMPLICIT MAIN
	'' ---------------------------------

	fb_End( 0 )
end function
 
'' but we still need a main to satisfy the linker and start-up code
'' NB: for actual use of '-entry' option this might be defined in 
''     another libray or framework

function main cdecl alias "main" _
	( _
		byval argc as long, _
		byval argv as zstring ptr ptr _
	) as long
	'' just call our custom main
	return custom_main( argc, argv )
end function
main4.bas: demonstrate '-entry name' without the internals
- this example tries to show the minimal code in fbc only. Could also do this by providing a main function in C or ASM but I won't go that far.

Code: Select all

'' main4.bas
'' - demostrate alternate named main function
''   as an alternate entry point for the implicit user main
'' - we must compile and link in separate steps, or give a non-existant
''   module name so that fbc doesn't generate the implicit user main 

'' compile: $ fbc -c -m main4 main4.bas -entry custom_main
'' compile: $ fbc main4.o
'' OR
'' compile: $ fbc main4.bas -entry custom_main

'' internally the implicit main function is now named "custom_main"
declare function custom_main cdecl alias "custom_main" _
	( _
		byval argc as long, _
		byval argv as zstring ptr ptr _
	) as long

'' But we still need a main() function to satisfy the linker and start-up code
'' - this might be defined in another libray or framework
'' - it's not so let's define it here for the demonstration
function main cdecl alias "main" _
	( _
		byval argc as long, _
		byval argv as zstring ptr ptr _
	) as long
	'' !!!TODO!!! stack alignment???
	'' just call our custom main for demonstration
	return custom_main( argc, argv )
end function


'' ---------------------------------
'' START OF USER'S IMPLICIT MAIN
'' internally this is named "custom_main" and will automatically be
'' called by our custom frame work


	print "hello"

'' END OF USER'S IMPLICIT MAIN
'' ---------------------------------
coderJeff
Site Admin
Posts: 4313
Joined: Nov 04, 2005 14:23
Location: Ontario, Canada
Contact:

Re: Compiler Option: -entry

Post by coderJeff »

What I want to say about '-entry name':
- it's a low level kind of tweak that most users should not need to worry about
- the addition is incomplete, but I think is worth adding now so that it's use can be explored and improved
- my wish is that we get feedback from users on where how the feature should develop
- it would be nice to eventually develop the capability of an explicit main that is enforced (warning or error) with the help of the compiler
- there is no other way currently to override fbc's use of the "main" symbol other than to always compile and link separately
- it should get documented even if it is incomplete or will change in future - a note in the wiki that the feature is being developed and may change in future should be a sufficient warning to users

I'm not sure if the examples in my last post make its usage less obscure.

By default, fbc defines a publicly exported 'main' symbol in the main module as required by the run time start-up system code.
The main purpose of this option, '-entry name' is to change the name of the publicly export symbol of the implicit user main function.

The full extent of why and when the '-entry' option should be used is yet to be fully explored and developed.
fxm
Moderator
Posts: 12081
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Compiler Option: -entry

Post by fxm »

1)
Thanks for all of this.

2)
fxm wrote:changelog.txt:
Version 1.09.0
[added]
- fbc: add '-entry name' command line option to set program entry point (TeeEmCee)
coderJeff wrote:Another description could be: '-entry name' specifies the public exported name of the implicit user main function.
Indeed, already this other short description is less leading to confusion.

3)
Documentation page:
Compiler Option: -entry
coderJeff
Site Admin
Posts: 4313
Joined: Nov 04, 2005 14:23
Location: Ontario, Canada
Contact:

Re: Compiler Option: -entry

Post by coderJeff »

fxm wrote:3)
Documentation page:
Compiler Option: -entry
Nice! You the man.

I am grateful you are able to take my (sometimes disconnected) statements and consolidate in to a cohesive documentation entry. Thank-you!
Post Reply