A static library is compiled code that can be later used when building an executable.
When the compiler makes an executable, the basic source files are first turned in to object files. The object files are then linked together to make an executable. When we compile source code, we don't necessarily have to make an executable. We could instead group all of the object files (made from sources) in to a single file called a static library.
The library is referred to as static, because when the object files which it contains are later linked in to an executable, a copy of all the needed code in the library is added to the executable.
Once the library is made, we can then use the code that it contains just as if we were compiling the source directly with our program.
Exchanging/Sharing variables with static library
A static library allows the direct sharing of variables by using the
Common or
Extern keyword, both in library code and module code.
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 (by value) or share data (by reference) with a shared library.
Simple example of static library
Following is a simple example of creating a static library using these three files:
- mylib.bas - the source for the library
- mylib.bi - the header for the library
- mytest.bas - a test program
Our library will be a single module providing a single function:
'' mylib.bas
'' compile with: fbc -lib mylib.bas
'' Add two numbers together and return the result
Public Function Add2( ByVal x As Integer, ByVal y As Integer ) As Integer
Return( x + y )
End Function
Compile the library with:
fbc -lib mylib.bas
The
-lib 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 library file, also called an archive,
libmylib.a. A library might contain many modules (source files) each with many functions, but for this simple example, it is just one each.
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:
'' mylib.bi
#inclib "mylib"
Declare Function Add2( ByVal x As Integer, ByVal y As Integer ) As Integer
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
#inclib statement will tell the compiler the name of a static library that we need to link with when eventually making an executable.
With our library (.a file) and a header (.bi file) we can try them out in a test program:
'' mytest.bas
'' compile with: fbc mytest.bas
#include Once "mylib.bi"
Print Add2(1,2)
The
#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:
Advanced example of OOP static library
Following is an advanced example of creating an OOP static library using these three files:
- varZstring.bi - the header for the library
- varZstring.bas - the source for the library
- varZstringTest.bas - a test program
Similar method than above to compile the library, then compile and execute the test program.
Header file for the library:
'' header file: 'varZstring.bi'
Type varZstring Extends ZString
Public:
Declare Constructor (ByRef z As Const ZString)
Declare Operator Cast () ByRef As ZString
Declare Operator Let (ByRef z As Const ZString)
Declare Property allocated () As Integer
Declare Destructor ()
Private:
Dim As ZString Ptr _p
Dim As UInteger _allocated
End Type
Declare Operator Len (ByRef v As varZstring) As Integer '' mandatory for the user code to call
'' the overload Len operator and
'' not the prebuilt-in Len operator
Note: Take care to declare also each overload procedure, because the absence of declaration will not necessarily lead to a compilation error if its usage in the user code is syntactically compatible with the pre-built in procedure, but the result will obviously not be as expected.
Source file for the library:
'' library module: 'varZstring.bas'
#include "varZstring.bi"
Constructor varZstring (ByRef z As Const ZString)
If This._p <> 0 Then
Deallocate(This._p)
End If
This._allocated = Len(z) + 1
This._p = CAllocate(This._allocated, SizeOf(ZString))
*This._p = z
End Constructor
Operator varZstring.Cast () ByRef As ZString
Return *This._p
End Operator
Operator varZstring.Let (ByRef z As Const ZString)
If This._allocated < Len(z) + 1 Then
Deallocate(This._p)
This._allocated = Len(z) + 1
This._p = CAllocate(This._allocated, SizeOf(ZString))
End If
*This._p = z
End Operator
Property varZstring.allocated () As Integer
Return This._allocated
End Property
Destructor varZstring ()
Deallocate(This._p)
This._p = 0
End Destructor
Operator Len (ByRef v As varZstring) As Integer
Return Len(Type<String>(v)) '' found nothing better than this
End Operator '' (or: 'Return Len(Str(v))')
Test program file:
'' test program: 'varZstringTest.bas'
#include "varZstring.bi" '' must contain also the overload Len operator declaration,
'' otherwise the prebuilt-in Len operator is called and applied
'' on the object variable (providing the length of its member data)
#inclib "varZstring" '' one can also put this line in the 'varZstring.bi' file
'' (and not in this file), but it seems a bit crooked
Print "VARIABLE",,, "| LEN| SIZEOF|"
Print "------------------------------------------|--------|--------|"
Dim As varZstring v = "FreeBASIC" '' adjusts memory allocation to minimum
Print "varZstring v:", "'" & v & "'",, "|"; Using "########|"; Len(v); v.allocated
Dim As ZString * 256 z
z = v
Print "Zstring z:", "'" & z & "'",, "|"; Using "########|"; Len(z); SizeOf(z)
v = z & " & SourceForge" '' only increases memory allocation if necessazy
Print "varZstring v:", "'" & v & "'", "|"; Using "########|"; Len(v); v.allocated
v = z & " & Wiki" '' only increases memory allocation if necessazy
Print "varZstring v:", "'" & v & "'", "|"; Using "########|"; Len(v); v.allocated
v.Constructor(v) '' readjusts memory allocation to minimum
Print "varZstring v:", "'" & v & "'", "|"; Using "########|"; Len(v); v.allocated
Sleep
Output:
VARIABLE | LEN| SIZEOF|
------------------------------------------|--------|--------|
varZstring v: 'FreeBASIC' | 9| 10|
Zstring z: 'FreeBASIC' | 9| 256|
varZstring v: 'FreeBASIC & SourceForge' | 23| 24|
varZstring v: 'FreeBASIC & Wiki' | 16| 24|
varZstring v: 'FreeBASIC & Wiki' | 16| 17|
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 libraries out of some code modules that seldom change can improve compile times dramatically.
Libraries can optionally contain debugging information specified with the
-g command line option.
A 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.
Object files, and therefore libraries, are platform specific and in some cases specific to a particular version of the compiler and FreeBASIC runtime library.
See also