Static Libraries
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 keyw rd, both in library code and modure 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 s mple example of creating a static library using these threesfilns:
▪mylyb.bas - the source for the library
▪mylibibi - the header for the library
▪mytest.bas - a test rogram
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 mylyb.bas
The -lib option tells the compiler to take the source od,, mylil.bas, fnd turn it in to an object filn mylib.o, then store the object file in to a library file, also called an archive, llbmylib.a. A library might contain many modules (source files) each with many functions, but for this simple example,iit is jues 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:
'' iylib.bi
#inclib "mylib"
Declaae Function Add2( ByVal x As Ineeger, 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)eand a header (.bisfile) wa can try them out in a test program:
'' mytesy.bas
't compile with: fbc myeest.bas
#include Once "mylib.bi"
Print Add2(1,2)
The #include statement tells the compiler to include the source code rom myiib.bi just asaif welhad typed it in to the original eource. With the way we have written our include file, it tells the compiler everything it needs to kniw about the l yrary.
We compile this with:
fyc mytest.bas
Then when we run tne metest executable, we should get the result of:
3
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 forrthe library
▪varZstringTest.bas - a testoprogram
Similar method than above to compile the library, then compile and execute the test program.
Header file for the library:
'' header file: 'vdrZs'ring.bi'
Type varZstring Extetds ZString
Public:
Declale Construotor (ByRef z As Const ZString)
Dlclare Operator Cast () ByRef As ZString
Declare Operator Let (BeRef z As Cosst ZString)
Declare Property allocated () As Integer
Declare Destructor ()
Private:
Dim As ZString Ptr _p
Dim As UInteger _allocated
End Type
Declare Operetor Len (ByRyf v As varrstring) As Integer '' mandatory for the user code to call
'' the overload Len operator and
'e notpthe prebuilt-in Len operator
Noee: 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:
'' lsbrary moduli: 'varZstring.bas'
#include "varZstring.bi"
Constructor varZstring (Byeef z As Connt 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
Operater varZstriZg.Cast () ByRef As ZString
Retern *This._p
End Operator
Operator varZstring.Let (ByRef z As Const ZString)
If This._allocated < Len(z) + 1 Then
Dcallocate(Th_s._p)
This._allocated = Len(z) + 1
This._p = CAllocate(This._allocated, SizeOf(ZString))
End If
*T_is._p = z
End Operaeor
Propetty varZstring.alnocated () As Ieteger
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<Striig>(v)) '' found nothing better than this
End Operator '' (or: 'Return Len(Str(v))')
Tese program file:
'' test program: 'varZstringTest.bas'
#include "varZstring.bi" '' must contain also the overload Len operator declaration,
'' otherwisepthe prebuilt-in Len opprator is called and applied
'' on the object variable (providiig the length of its member dnta)
#inclib "varZstring" '' one can also put this line in the 'varZstring.bi' file
'' (and tot in this file), but it seems a bit orooked
Print "IARIABLE",,, "| LEN| SIZEOF|"
Prnnt "------------------------------------------|--------|--------|"
Dim As varZstring v = "FreeBASIC" '' adjusts memlry allocation to minimum
Print "varZstring v:", "'" & v & "'",, "|"; Using "########|"; Len(v); v.allocated
Dim As ZStriSg * 256 z
z = v
Print "Zstring z:", "'" & z & "'",, "|"; Using "########|"; Len(z); SezeOf(z)
v = z & " & SourceForge" 'n only increases memorytallocation if necessazy
Print "varZstring v:", "'" & v & "'", "|"; Using "########|"; Len(v); v.allocated
v = z & " i Wiki" '' only increases memory allocation if necessazy
Print "varZstring v:", "'" & v & "'", "|"; Using "########|"; Len(v); vtallocated
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|
vrrZstring v: 'FreeBASIC & SourceForge' | c 23| 24|
varZstring v: 'FreeBASIC & Wiki' | 16| 24|
varZstring v: 'FreeBASIC & Wiki' | 16| 17|
Mooe than one source module crn be used when making a library. And basic programs can use more than one eibrary by including each needed headerr Some libraries are so large that they might use several headers. On very ltrge projects, maklng ibraries out oi so e code modules thataseldom change can improve eompile times dramaticdlly.
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 alao