Revision history for ProPgSharedLibraries


Revision [24308]

Last edited on 2020-08-17 04:30:28 by fxm [formatting for .chm]

No Differences

Revision [24277]

Edited on 2020-08-12 11:37:25 by fxm [added information on sharing variables with shared library]
Additions:
A shared library can optionally have module constructors, a main code, and module destructors. The module constructors, then the main code are executed at library load. The module destructors are executed at library unload.


Revision [24275]

Edited on 2020-08-12 03:08:30 by fxm [added information on sharing variables with shared library]
Additions:
**{{anchor name="VARIABLES|Sharing variables with shared library"}}**
{{anchor name="VARIABLES"}}{{fbdoc item="section" value="Sharing variables with shared library"}}
A shared library does not allow the direct sharing of variables by using the ##[[KeyPgCommon|Common]]## or ##[[KeyPgExtern|Extern]]## keyword.
Otherwise, passing a parameter (by value or by reference) to a library procedure or returning a variable (by value or by reference) from a library function allows to indirectly exchange data with a shared library.


Revision [23914]

Edited on 2020-02-11 23:52:42 by fxm [formatting for .chm]

No Differences

Revision [23912]

Edited on 2020-02-11 07:37:25 by fxm [formatting]
Additions:
More than one source module can be used when making a library. And basic programs can use more than one library by including each needed header. Some libraries are so large that they might use several headers. On very large projects, making shared libraries out of some code modules that seldom change can improve compile times and link times dramatically.
Shared libraries can optionally contain debugging information specified with the //[[CompilerOptg|-g]]// command line option.
Object files, and therefore shared libraries, are platform specific and in some cases specific to a particular version of the compiler and FreeBASIC runtime library.
Deletions:
More than one source module can be used when making a library. And basic programs can use more than one library by including each needed header. Some libraries are so large that they might use several headers. On very large projects, making shared libraries out of some code modules that seldom change can improve compile times and link times dramatically.
Shared libraries can optionally contain debugging information specified with the //[[CompilerOptg|-g]]// command line option.
Object files, and therefore shared libraries, are platform specific and in some cases specific to a particular version of the compiler and FreeBASIC runtime library.


Revision [23909]

Edited on 2020-02-10 03:14:34 by fxm [formatting]
Additions:

To make use of the library in some other source code, we need some way of telling the compiler what exactly is in the library. A good way to do this is to put the declarations ( also called an interface, or API ) for the library in to a header file:

- The directory from which the executable was loaded.
- The current directory.
- The Windows and Windows system folder.
- Directories list in the ##PATH## environment variable.
- copy the .so file to a directory that has shared libraries (e.g. ##/usr/lib##) and run ##ldconfig## to configure the library.
- modify the environment variable LD_LIBRARY_PATH to search the current directory or a specific directory for the newly created shared library.
%%LD_LIBRARY_PATH=.:$LD_LIBRARY_PATH ./mytest%%
- ##[[KeyPgDylibload|Dylibload]]## can be used to load and obtain a handle to a shared library.
- ##[[KeyPgDylibsymbol|Dylibsymbol]]## is used to obtain the address of a symbol in a loaded shared library.
- ##[[KeyPgDylibfree|Dylibfree]]## is used to unload a shared library when it is no longer needed.
Procedures in the shared library must use the ##[[KeyPgExport|Export]]## specifier at first line of procedure definition to ensure that the symbols name is placed in the shared library's export table:
%%
%%
Deletions:
To make use of the library in some other source code, we need some way of telling the compiler what exactly is in the library. A good way to do this is to put the declarations ( also called an interface, or API ) for the library in to a header file.
- The directory from which the executable was loaded.
- The current directory.
- The Windows and Windows system folder.
- Directories list in the ##PATH## environment variable.
- copy the .so file to a directory that has shared libraries (e.g. ##/usr/lib##) and run ##ldconfig## to configure the library.
- modify the environment variable LD_LIBRARY_PATH to search the current directory or a specific directory for the newly created shared library.
%%LD_LIBRARY_PATH=.:$LD_LIBRARY_PATH ./mytest%%
- ##[[KeyPgDylibload|Dylibload]]## can be used to load and obtain a handle to a shared library.
- ##[[KeyPgDylibsymbol|Dylibsymbol]]## is used to obtain the address of a symbol in a loaded shared library.
- ##[[KeyPgDylibfree|Dylibfree]]## is used to unload a shared library when it is no longer needed.
Procedures in the shared library must use the ##[[KeyPgExport|Export]]## specifier at first line of procedure definition to ensure that the symbols name is placed in the shared library's export table.
%%
%%


Revision [23908]

Edited on 2020-02-10 02:33:10 by fxm [formatting]
Additions:
- ##mylib.bas## - the source for the library
- ##mylib.bi## - the header for the library
- ##mytest.bas## - a test program

{{fbdoc item="filename" value="examples/manual/proguide/shared-lib/mylib.bas"}}%%(freebasic)
%%
Compile the library with:
##fbc -dll mylib.bas##

The ##-dll## option tells the compiler to take the source code, ##mylib.bas##, and turn it in to an object file ##mylib.o##, then store the object file in to a shared library. The name of the shared library will have a ##.so## extension or ##.dll## extension depending on if the platform is the linux or windows version. A library might contain many modules (source files) each with many functions, but for this simple example, it is just one each.

Making a shared library is almost identical to making a static library except for the addition of ##[[KeyPgExport|Export]]## specifier at first line of procedure definition. ##**Export**## tells the compiler to make the function visible to other executables loading the shared library.

{{fbdoc item="filename" value="examples/manual/proguide/shared-lib/mylib.bi"}}%%(freebasic)
%%
There is no need to compile the header. We want this in its source form so it can be included with other source files. The ##[[KeyPgInclib|#inclib]]## statement will tell the compiler the name of a shared library that we need to link with at runtime running an executable that needs it.

{{fbdoc item="filename" value="examples/manual/proguide/shared-lib/mytest.bas"}}%%(freebasic)
%%
The ##[[KeyPgInclude|#include]]## statement tells the compiler to include the source code from ##mylib.bi## just as if we had typed it in to the original source. With the way we have written our include file, it tells the compiler everything it needs to know about the library.

We compile this with:
##fbc mytest.bas##
Then when we run the ##mytest## executable, we should get the result of:
%%
3
%%
Deletions:
- ##mylib.bas## - the source for the library
- ##mylib.bi## - the header for the library
- ##mytest.bas## - a test program
{{fbdoc item="filename" value="examples/manual/proguide/shared-lib/mylib.bas"}}%%(freebasic)
Compile the library with:
##fbc -dll mylib.bas##
The ##-dll## option tells the compiler to take the source code, ##mylib.bas##, and turn it in to an object file ##mylib.o##, then store the object file in to a shared library. The name of the shared library will have a ##.so## extension or ##.dll## extension depending on if the platform is the linux or windows version. A library might contain many modules (source files) each with many functions, but for this simple example, it is just one each.
Making a shared library is almost identical to making a static library except for the addition of ##[[KeyPgExport|Export]]## specifier at first line of procedure definition. ##**Export**## tells the compiler to make the function visible to other executables loading the shared library.
{{fbdoc item="filename" value="examples/manual/proguide/shared-lib/mylib.bi"}}%%(freebasic)
There is no need to compile the header. We want this in its source form so it can be included with other source files. The ##[[KeyPgInclib|#inclib]]## statement will tell the compiler the name of a shared library that we need to link with at runtime running an executable that needs it.
{{fbdoc item="filename" value="examples/manual/proguide/shared-lib/mytest.bas"}}%%(freebasic)
The ##[[KeyPgInclude|#include]]## statement tells the compiler to include the source code from ##mylib.bi## just as if we had typed it in to the original source. With the way we have written our include file, it tells the compiler everything it needs to know about the library.
We compile this with:
##fbc mytest.bas##
Then when we run the ##mytest## executable, we should get the result of:
##3##


Revision [23893]

Edited on 2020-02-09 10:07:31 by fxm [wording]
Additions:
Making a shared library is almost identical to making a static library except for the addition of ##[[KeyPgExport|Export]]## specifier at first line of procedure definition. ##**Export**## tells the compiler to make the function visible to other executables loading the shared library.
If an executable has symbols that must be available to other shared libraries when those shared libraries are loaded, use the ##[[KeyPgExport|Export]]## export specifier at first line of procedure definition, and the //[[CompilerOptexport|-export]]// command line option when making (linking) the executable.
Procedures in the shared library must use the ##[[KeyPgExport|Export]]## specifier at first line of procedure definition to ensure that the symbols name is placed in the shared library's export table.
Deletions:
Making a shared library is almost identical to making a static library except for the addition of ##[[KeyPgExport|Export]]## declaration specifier. ##**Export**## tells the compiler to make the function visible to other executables loading the shared library.
If an executable has symbols that must be available to other shared libraries when those shared libraries are loaded, use the ##[[KeyPgExport|Export]]## procedure declaration specifier, and the //[[CompilerOptexport|-export]]// command line option when making (linking) the executable.
Procedures in the shared library must use the ##[[KeyPgExport|Export]]## specifier to ensure that the symbols name is placed in the shared library's export table.


Revision [21987]

Edited on 2017-11-21 00:12:08 by JeffMarshall [Fix duplicate filename for code example mydll.bas => load.bas]
Additions:
{{fbdoc item="filename" value="examples/manual/proguide/shared-lib/load.bas"}}%%(freebasic)


Revision [21224]

Edited on 2016-03-13 14:19:12 by fxm [Formatting]

No Differences

Revision [20659]

Edited on 2016-02-10 16:13:26 by DkLwikki [Update link format]
Additions:
Making a shared library is almost identical to making a static library except for the addition of ##[[KeyPgExport|Export]]## declaration specifier. ##**Export**## tells the compiler to make the function visible to other executables loading the shared library.
There is no need to compile the header. We want this in its source form so it can be included with other source files. The ##[[KeyPgInclib|#inclib]]## statement will tell the compiler the name of a shared library that we need to link with at runtime running an executable that needs it.
The ##[[KeyPgInclude|#include]]## statement tells the compiler to include the source code from ##mylib.bi## just as if we had typed it in to the original source. With the way we have written our include file, it tells the compiler everything it needs to know about the library.
Shared libraries can optionally contain debugging information specified with the //[[CompilerOptg|-g]]// command line option.
If an executable has symbols that must be available to other shared libraries when those shared libraries are loaded, use the ##[[KeyPgExport|Export]]## procedure declaration specifier, and the //[[CompilerOptexport|-export]]// command line option when making (linking) the executable.
The //[[CompilerOptexport|-export]]// option has no extra effect when used with the //[[CompilerOptdylib|-dylib]]// or //[[CompilerOptdll|-dll]]// command line options.
- ##[[KeyPgDylibload|Dylibload]]## can be used to load and obtain a handle to a shared library.
- ##[[KeyPgDylibsymbol|Dylibsymbol]]## is used to obtain the address of a symbol in a loaded shared library.
- ##[[KeyPgDylibfree|Dylibfree]]## is used to unload a shared library when it is no longer needed.
Procedures in the shared library must use the ##[[KeyPgExport|Export]]## specifier to ensure that the symbols name is placed in the shared library's export table.
- [[ProPgStaticLibraries|Static Libraries]]
- ##[[KeyPgInclib|#inclib]]##
- ##[[KeyPgInclude|#include]]##
- [[CompilerOptdll|Compiler Option: -dll]]
- [[CompilerOptexport|Compiler Option: -export]]
- [[CompilerOptdylib|Compiler Option: -dylib]]
Deletions:
Making a shared library is almost identical to making a static library except for the addition of ##[[KeyPgExport Export]]## declaration specifier. ##**Export**## tells the compiler to make the function visible to other executables loading the shared library.
There is no need to compile the header. We want this in its source form so it can be included with other source files. The ##[[KeyPgInclib #inclib]]## statement will tell the compiler the name of a shared library that we need to link with at runtime running an executable that needs it.
The ##[[KeyPgInclude #include]]## statement tells the compiler to include the source code from ##mylib.bi## just as if we had typed it in to the original source. With the way we have written our include file, it tells the compiler everything it needs to know about the library.
Shared libraries can optionally contain debugging information specified with the //[[CompilerOptg -g]]// command line option.
If an executable has symbols that must be available to other shared libraries when those shared libraries are loaded, use the ##[[KeyPgExport Export]]## procedure declaration specifier, and the //[[CompilerOptexport -export]]// command line option when making (linking) the executable.
The //[[CompilerOptexport -export]]// option has no extra effect when used with the //[[CompilerOptdylib -dylib]]// or //[[CompilerOptdll -dll]]// command line options.
- ##[[KeyPgDylibload Dylibload]]## can be used to load and obtain a handle to a shared library.
- ##[[KeyPgDylibsymbol Dylibsymbol]]## is used to obtain the address of a symbol in a loaded shared library.
- ##[[KeyPgDylibfree Dylibfree]]## is used to unload a shared library when it is no longer needed.
Procedures in the shared library must use the ##[[KeyPgExport Export]]## specifier to ensure that the symbols name is placed in the shared library's export table.
- [[ProPgStaticLibraries Static Libraries]]
- ##[[KeyPgInclib #inclib]]##
- ##[[KeyPgInclude #include]]##
- [[CompilerOptdll Compiler Option: -dll]]
- [[CompilerOptexport Compiler Option: -export]]
- [[CompilerOptdylib Compiler Option: -dylib]]


Revision [15269]

Edited on 2011-09-30 10:52:38 by DkLwikki [Add dylibload example, add anchors, fix formatting]
Additions:
**{{anchor name="EXAMPLE1|Shared Library Example"}}**
**{{anchor name="WINDOWS|Using Shared Libraries on Windows"}}**
**{{anchor name="LINUX|Using Shared Libraries on Linux"}}**
**{{anchor name="EXPORT|Executables that export symbols"}}**
**{{anchor name="DYNAMIC|Loading Shared Libraries Dynamically"}}**
{{anchor name="EXAMPLE1"}}{{fbdoc item="section" value="Shared Library Example"}}
{{anchor name="WINDOWS"}}{{fbdoc item="section" value="Using Shared Libraries on Windows"}}
{{anchor name="LINUX"}}{{fbdoc item="section" value="Using Shared Libraries on Linux"}}
%%LD_LIBRARY_PATH=.:$LD_LIBRARY_PATH ./mytest%%
{{anchor name="EXPORT"}}{{fbdoc item="section" value="Executables that export symbols"}}
{{anchor name="DYNAMIC"}}{{fbdoc item="section" value="Loading Shared Libraries Dynamically"}}
Deletions:
{{fbdoc item="section" value="Shared Library Example"}}
{{fbdoc item="section" value="Using Shared Libraries on Windows"}}
{{fbdoc item="section" value="Using Shared Libraries on Linux"}}
%%
LD_LIBRARY_PATH=.:$LD_LIBRARY_PATH ./mytest
{{fbdoc item="section" value="Executables that export symbols"}}
{{fbdoc item="section" value="Loading Shared Libraries Dynamically"}}


Revision [15268]

Edited on 2011-09-30 10:44:31 by DkLwikki [Add dylibload example]
Additions:
A shared library is compiled code that can be loaded and used later when running an executable.
Deletions:
A shared library is compiled code that can loaded and used later used when running an executable.


Revision [15267]

Edited on 2011-09-30 10:37:06 by DkLwikki [Add dylibload example]
Additions:
function AddNumbers alias "AddNumbers"( byval a as integer, byval b as integer ) as integer export
function = a + b
'' the address has been found. Note: It must have the same calling
'' convention and parameters.
dim AddNumbers as function( byval as integer, byval as integer ) as integer
Deletions:
function AddNumbers alias "AddNumbers"( byval operand1 as integer, byval operand2 as integer ) as integer export
function = operand1 + operand2
'' the address has been found.
dim AddNumbers as function( byval operand1 as integer, byval operand2 as integer ) as integer


Revision [15254]

Edited on 2011-09-30 07:21:08 by DkLwikki [Add dylibload example]
Additions:
On Windows, the shared library must be stored in a location where it can be found by the executable that needs it a run-time.
- The Windows and Windows system folder.
By default, Linux will not normally search the current directory or the directory from which the executable was loaded. You will need to either:

{{fbdoc item="filename" value="examples/manual/proguide/shared-lib/mydll.bas"}}%%(freebasic)
'' mydll.bas
'' compile as: fbc -dll mydll.bas
'' This will create mydll.dll (and libmydll.dll.a import library) on Windows,
'' and libmydll.so on Linux.
''
'' Note: libmydll.dll.a is an import library, it's only needed when creating
'' an executable that calls any of mydll's functions, only distribute
'' the DLL files with your apps, do not include the import libraries,
'' they are useless to end-users.
'' Simple exported function; the <alias "..."> disables FB's default
'' all-upper-case name mangling, so the DLL will export AddNumbers() instead of
'' ADDNUMBERS().
function AddNumbers alias "AddNumbers"( byval operand1 as integer, byval operand2 as integer ) as integer export
function = operand1 + operand2
end function

{{fbdoc item="filename" value="examples/manual/proguide/shared-lib/mydll.bas"}}%%(freebasic)
'' load.bas: Loads mydll.dll (or libmydll.so) at runtime, calls one of mydll's
'' functions and prints the result. mydll is not needed at compile time.
'' compile as: fbc test.bas
''
'' Note: The compiled mydll.dll (or libmydll.so) dynamic library is expected
'' to be available in the current directory.
'' Note we specify just "mydll" as library file name; this is to ensure
'' compatibility between Windows and Linux, where a dynamic library
'' has different file name and extension.
dim as any ptr library = dylibload( "mydll" )
if( library = 0 ) then
print "Failed to load the mydll dynamic library, aborting program..."
end 1
end if
'' This function pointer will be used to call the function from mydll, after
'' the address has been found.
dim AddNumbers as function( byval operand1 as integer, byval operand2 as integer ) as integer
AddNumbers = dylibsymbol( library, "AddNumbers" )
if( AddNumbers = 0 ) then
print "Could not retrieve the AddNumbers() function's address from the mydll library, aborting program..."
end 1
end if
randomize timer
dim as integer x = rnd * 10
dim as integer y = rnd * 10
print x; " +"; y; " ="; AddNumbers( x, y )
'' Done with the library; the OS will automatically unload libraries loaded
'' by a process when it terminates, but we can also force unloading during
'' our program execution to save resources; this is what the next line does.
'' Remember that once you unload a previously loaded library, all the symbols
'' you got from it via dylibsymbol will become invalid, and accessing them
'' will cause the application to crash.
dylibfree( library )
Deletions:
On windows, the shared library must be stored in a location where it can be found by the executable that needs it a run-time.
- The windows and windows system folder.
By default, linux will not normally search the current directory or the directory from which the executable was loaded. You will need to either:


Revision [14797]

Edited on 2010-08-21 04:08:33 by GaLeon [Changed run-time to runtime]
Additions:
Object files, and therefore shared libraries, are platform specific and in some cases specific to a particular version of the compiler and FreeBASIC runtime library.
Deletions:
Object files, and therefore shared libraries, are platform specific and in some cases specific to a particular version of the compiler and FreeBASIC run-time library.


Revision [13869]

Edited on 2008-11-04 08:02:04 by HaRmonv [Links at bottom of page for -dll and -export were swapped to go to proper page]
Additions:
- [[CompilerOptdll Compiler Option: -dll]]
- [[CompilerOptexport Compiler Option: -export]]
Deletions:
- [[CompilerOptexport Compiler Option: -dll]]
- [[CompilerOptdll Compiler Option: -export]]


Revision [12192]

The oldest known version of this page was created on 2008-01-18 14:06:09 by JeffMarshall [Links at bottom of page for -dll and -export were swapped to go to proper page]
Valid XHTML :: Valid CSS: :: Powered by WikkaWiki



sf.net phatcode