fbdoc: wiki snapshot 2018-10-08

Author: jayrm

doc/manual/cache/CatPgFunctIndex.wakka

@@ -408,7 +408,7 @@ List of ""FreeBASIC"" keywords sorted by the function they perform.
 	- {{fbdoc item="keyword" value="KeyPgDdfbdos|__FB_DOS__"}}
 	- {{fbdoc item="keyword" value="KeyPgDdfberr|__FB_ERR__"}}
 	- {{fbdoc item="keyword" value="KeyPgDdfbfpmode|__FB_FPMODE__"}}
-	- {{fbdoc item="keyword" value="KeyPgDdfbfpu|__FB_FPFPU__"}}
+	- {{fbdoc item="keyword" value="KeyPgDdfbfpu|__FB_FPU__"}}
 	- {{fbdoc item="keyword" value="KeyPgDdfbfreebsd|__FB_FREEBSD__"}}
 	- {{fbdoc item="keyword" value="KeyPgDdfbgcc|__FB_GCC__"}}
 	- {{fbdoc item="keyword" value="KeyPgDdfbgui|__FB_GUI__"}}

doc/manual/cache/DevBootstrap.wakka

@@ -6,12 +6,29 @@ fbc is written in FB itself, so you need a working fbc to build a new fbc. How t
 
 	The ""FreeBASIC-x.xx.x-source-bootstrap"" package contains the FB sources plus precompiled compiler sources, for multiple targets. After extracting, this can be built without requiring an existing fbc:
 	%%make bootstrap%%
-	
 	(as long as the package contains the precompiled sources for the target system)
 
 	This package can be created by running:
 	%%make bootstrap-dist%%
 
+{{fbdoc item="section" value="Bootstrapping by creating and using a bootstrap package"}}
+
+	1) On a system with a working fbc compiler, create the bootstrap package:
+		%%make bootstrap-dist%%
+		creates ##FreeBASIC-x.xx.x-source-bootstrap.tar.xz##
+		
+	1) Take the bootstrap package to the new system and use it to build the bootstrap compiler:
+		%%cd ~
+tar xf ~/FreeBASIC-x.xx.x-source-bootstrap.tar.xz
+cd FreeBASIC-x.xx.x-source-bootstrap
+make bootstrap
+%%
+		
+	1) On the new system, assuming sources are in ~/fbc, use the bootstrap compiler to build fbc for the new system
+		%%cd ~/fbc
+make 'FBC=~/FreeBASIC-x.xx.x-source-bootstrap/bin/fbc -i ~/FreeBASIC-x.xx.x-source-bootstrap/inc'
+%%		
+		
 	Doing ##make bootstrap-dist##, taking the package to the target system, and then doing ##make bootstrap## can replace the manual steps below, as long as the target is already supported by these commands in the FB makefile.
 
 {{fbdoc item="section" value="Bootstrapping by precompiling the compiler sources"}}

doc/manual/cache/KeyPgAlias.wakka

@@ -1,5 +1,5 @@
 {{fbdoc item="title" value="ALIAS"}}----
-Clause of the ##[[KeyPgSub|Sub]]## and ##[[KeyPgFunction|Function]]## statements that provides an alternate internal name
+Clause of the ##[[KeyPgSub|Sub]]## and ##[[KeyPgFunction|Function]]## statements that provides an alternate internal name.
 
 {{fbdoc item="syntax"}}##
 	[[[KeyPgDeclare|declare]]] { [[KeyPgSub|sub]] | [[KeyPgFunction|function]] } //usablename// **Alias "//alternatename//"** (...)
@@ -23,6 +23,8 @@ Clause of the ##[[KeyPgSub|Sub]]## and ##[[KeyPgFunction|Function]]## statements
 	##Alias## is commonly used for procedures in libraries written in other languages when such procedure names are valid in the other language but invalid in BASIC.  When using ##Alias## with ##[[KeyPgDeclare|Declare]]##, only the alternate name is used by the linker.
 
 	Differently from normal procedure names, ##Alias## does not change the case of the alternate name, so it is useful when external code requires an exported function with a particular name or with a particular case.
+	
+	##Alias## can also be used as modifier that specifies an alternate mangling for procedure parameters.  For example ##extern ""c+""""+"" : declare sub proc( byval as long **alias "long"** ) : end extern##.  This form of ##Alias## can only be used as in //##[unsigned] [u]long alias "long"##//.  The specific purpose is to allow FreeBASIC to call external ""c+""""+"" procedures (on win-64) requiring a 32-bit ##'long int'## type.  Usage of ##Alias## in this way affects win-64 targets only, and is ignored on all other targets.
 
 {{fbdoc item="ex"}}
 

doc/manual/cache/KeyPgDdfbgui.wakka

@@ -0,0 +1,29 @@
+{{fbdoc item="title" value="__FB_GUI__"}}----
+Intrinsic define (macro value) set by the compiler
+
+{{fbdoc item="syntax"}}##
+	""__FB_GUI__""
+##
+{{fbdoc item="desc"}}
+	##""__FB_GUI__""## indicates if the executable subsystem option '-s gui' was specified on the command line at the time of compilation.
+	
+	Returns non-zero (-1) if the executable subsystem option '-s gui' was specified. Returns zero (0) otherwise (no executable subsystem option specified, or executable subsystem option '-s console' specified).
+
+{{fbdoc item="ex"}}
+{{fbdoc item="filename" value="examples/manual/defines/fbgui.bas"}}%%(freebasic)
+#if __FB_GUI__ <> 0
+		#print Executable subsystem: gui
+#else 
+		#print Executable subsystem: console
+#endif
+%%
+{{fbdoc item="target"}}
+	- Supported on Windows and Cygwin only.
+
+{{fbdoc item="diff"}}
+	- New to ""FreeBASIC""
+
+{{fbdoc item="see"}}
+	- [[CompilerOpts|Compiler Option: -s]]
+
+{{fbdoc item="back" value="CatPgDddefines|Intrinsic Defines"}}

doc/manual/cache/KeyPgModuleConstructor.wakka

@@ -11,15 +11,23 @@ Specifies execution of a procedure before module-level code
 
 	The procedure must have an empty parameter list.  A compile-time error will be generated if the ##**Constructor**## keyword is used in a Sub definition having one or more parameters. In a set of overloaded procedures, only one (1) constructor may be defined because of the ambiguity of having multiple Subs which take no arguments.
 
-	In a single module, constructors normally execute in the reverse order in which they are defined.
+	In a single module, depending on the build and run-time environment of the target system:
+		- constructors may execute in which they are defined, or reverse order
+		- constructors may execute before or after global static variables having constructors
+		- constructors may execute before or after other module constructors having ##//priority//## attribute
+		- constructors with ##//priority//## attribute may execute before or after global static variables having constructors
 
-	The ##//priority//## attribute, an integer between 101 and 65535, can be used to force constructors to be executed in a certain order.  The value of ##//priority//## has no specific meaning, only the relationship of the number with other constructor priorities.  101 is the highest priority and is executed first.  All constructors having a ##//priority//## attribute are executed before constructors with no attribute.  The priority value of 65535 is the same as not assigning a priority value.
+	The ##//priority//## attribute, an integer between 101 and 65535, can be used to force constructors to be executed in a certain order, relative to other constructors also having ##//priority//## attribute.  The value of ##//priority//## has no specific meaning, only the relationship of the number with other constructor priorities.  101 is the highest priority and is executed first, relative to other constructors also having ##//priority//## attribute.
 
 	A module may define multiple constructor procedures, and multiple modules may define additional constructors provided no two ##[[KeyPgPublic|Public]]## constructors share the same //procedure_name//.
 
 	When linking with modules that also define constructors, the order of execution is not guaranteed at link-time unless the ##//priority//## attribute is used. Therefore, special care should be taken when using constructors that may call on a secondary module also defining a constructor.  In such a case it is advisable to use a single constructor that explicitly calls initialization procedures in those modules.
 
-	**Note:** A public static member procedure (Sub having empty parameter list) can also be defined as module constructor (also with the ##**Constructor**## keyword only used in Sub definition).
+	Public static member procedures (a ##[[KeyPgMemberSub|Sub]]## having an empty parameter list), of user defined ##[[KeyPgType|type]]## can be defined as a module constructor, by adding the ##**Constructor**## keyword used in the sub procedure definition.
+	
+	Initialization of static simple numeric type variables, that have a value that can be determined at compile time (for example, default zero, constants, pointers to static objects, pointers to functions, etc), are initialized before any code is executed.  These values are part of the executable image and have an initial value when the executable is loaded in to memory.  Trivial static globals where no code is needed to initialize, are guaranteed to be initialized and can be reliably used in all code, including global static object constructors and module constructors.
+	
+	The module constructor feature exposes a low-level link-time feature of the build and run-time environment.  Accessing global static objects having constructors from module constructors should be avoided due to variations in execution order on different build systems.
 
 {{fbdoc item="ex"}}
 {{fbdoc item="filename" value="examples/manual/procs/mod-ctor.bas"}}%%(freebasic)

doc/manual/cache/KeyPgModuleDestructor.wakka

@@ -11,15 +11,23 @@ Specifies execution of a procedure at program termination
 
 	The procedure must have an empty parameter list.  A compile-time error will be generated if the ##**Destructor**## keyword is used in a Sub definition having one or more parameters. In a set of overloaded procedures, only one (1) destructor may be defined because of the ambiguity of having multiple Subs which take no arguments.
 
-	In a single module, destructors normally execute in the order in which they are defined.
+	In a single module, depending on the build and run-time environment of the target system:
+		- destructors may execute in which they are defined, or reverse order
+		- destructors may execute before or after global static variables having dstructors
+		- destructors may execute before or after other module destructors having ##//priority//## attribute
+		- destructors with ##//priority//## attribute may execute before or after global static variables having destructors
 
-	The ##//priority//## attribute, an integer between 101 and 65535, can be used to force destructors to be executed in a certain order.  The value of ##//priority//## has no specific meaning, only the relationship of the number with other destructor priorities. 101 is the lowest priority and is executed last.  All destructors having a ##//priority//## attribute are executed after destructors with no attribute.  The priority value of 65535 is the same as not assigning a priority value.
+	The ##//priority//## attribute, an integer between 101 and 65535, can be used to force destructors to be executed in a certain order.  The value of ##//priority//## has no specific meaning, only the relationship of the number with other destructor priorities. 101 is the lowest priority and is executed last, relative to other destructors also having ##//priority//## attribute.
 
 	A module may define multiple destructor procedures.  Destructor procedures may also appear in more than one module. All procedures defined with the syntax shown above will be added to the list of procedures to be called during the program's termination.
 
 	The order in which destructors defined in multiple modules are executed is known only at link time.  Therefore, special care should be taken when using destructors that may call on a secondary module also defining a destructors.  In such a case it is advisable to use a single destructor that explicit calls termination procedures in multiple modules to ensure a graceful termination of the application.
 
 	Destructors will be called if the program terminates normally or if error-checking is enabled and the program terminates abnormally.
+	
+	Public static member procedures (a ##[[KeyPgMemberSub|Sub]]## having an empty parameter list), of user defined ##[[KeyPgType|type]]## can be defined as a module destructor, by adding the ##**Constructor**## keyword used in the sub procedure definition.
+	
+	The module destructor feature exposes a low-level link-time feature of the build and run-time environment.  Accessing global static objects having destructors from module destructors should be avoided due to variations in execution order on different build systems.
 
 {{fbdoc item="ex"}}
 	{{fbdoc item="filename" value="examples/manual/procs/mod-dtor.bas"}}%%(freebasic)

doc/manual/cache/KeyPgOpNew.wakka

@@ -17,7 +17,7 @@ Operator to dynamically allocate memory and construct data of a specified type.
 		Exact number of elements to allocate.
 
 {{fbdoc item="ret"}}
-	A pointer of type [[DataType|datatype]] to the newly allocated data.
+	A pointer of type [[DataType|datatype]] to the newly allocated data, or null pointer if the memory allocation failed.
 
 {{fbdoc item="desc"}}
 	The ##**New Expression**## operator dynamically allocates memory and constructs a specified data type.
@@ -32,6 +32,10 @@ Operator to dynamically allocate memory and construct data of a specified type.
 
 	Specifying an initial value of ##[[KeyPgAny|Any]]##, as in ##**New** //datatype//[//count//] {**Any**}## will allocate memory for the array, but not initialize the data.  This is only valid on data types that do not have constructors (otherwise for data types with constructors, syntax of simple memory allocation with pointer conversion, like //Cptr(datatype Ptr, Allocate(count * Sizeof(datatype)))//, can be substituted to the invalid use of New...Any).
 
+	The total memory, in bytes, to be allocated with ##**New** //datatype//[//count//]## expression is calculated as ##//sizeof(datatype) * count//##, plus ##//sizeof(uinteger)//## if there is an implicit or explicit ##[[KeyPgDestructor|Destructor]]##.  The total memory requested in bytes to be allocated must not overflow the value that can be held by a ##[[KeyPgUinteger|Uinteger]]##.  The extra ##//uinteger//##, if allocated, stores the number of elements as part of the allocation, so that ##[[KeyPgOpDelete|Delete Statement]]## can determine the count of destructors to call.
+	
+	If the memory allocation fails, a null pointer is returned and no constructors are called.
+	
 	The dynamic memory allocation process part provided by the ##**New Expression**## operator can be overloaded for user-defined types as a member operator ##[[KeyPgOpNewOverload|New Overload]]##. The following process part for data construction can never be modified.
 
 	**Note:** Using ##//pointer// = **New** //datatype//[//count//]## may be unsafe if ##//pointer//## was declared with a type different from ##//datatype//## (for sub-type polymorphism purpose for example), because the pointer arithmetic fails to access the elements if the pointer type size is different from the size of ##//datatype//## (when using ##{{fbdoc item="keyword" value="KeyPgOpPtrIndex|Operator [] (Pointer index)"}}## or adding an offset (element number) to the pointer, or even when ##**Delete[] Statement**## itself (the array-version of ##[[KeyPgOpDelete|Delete Statement]]##) must destroy the elements).

doc/manual/cache/KeyPgTypeTemp.wakka

@@ -28,6 +28,8 @@ Creates a temporary copy of a user defined type
 
 	It can also be used as an even shorter shortcut than ##[[KeyPgWith|With]]## (see below) if you are changing all the data-fields (or the n firsts only).
 
+	A temporary object is destroyed at the end of execution of the statement (where it's defined), but its corresponding allocated memory is not released and remains available (unused) until going out the scope where statement is.
+	
 	Note: ##[[KeyPgStatic|Static]]## qualifier used at procedure definition level does not apply to temporary types.
 
 {{fbdoc item="ex"}}