{{fbdoc item="title" value="Using FreeBASIC Built Libraries with GCC"}}----
//by Jeff Marshall//

Shows how to create a static library with ""FreeBASIC"" and then call it from a C program using GCC as the compiler.

This article shows Windows usage throughout, but application to ""FreeBASIC"" on other platforms is similar.

{{fbdoc item="section" value="In this tutorial:"}}
	{{anchor name="S1|A Simple Test"}}
	{{anchor name="S2|FreeBASIC Library With Dependencies"}}
	{{anchor name="S3|Using FreeBASIC as a Smart Linker"}}


{{anchor name="S1"}}{{fbdoc item="section" value="A Simple Test"}}

For this simple test we are going to create a ""FreeBASIC"" static library, one without any dependencies.  This will make it easier the first time around, and will allow us to check that the basics are working:

First we need a library, and for for this it will be just a single trivial function that will add two integers together and return the result.  Notice the use of ##**cdecl**## and ##Alias## in our procedure definition.  By default, C uses the ##**cdecl**## calling convention.  Using ##**alias**## in the ""FreeBASIC"" declaration makes matching case sensitivity between ""FreeBASIC"" and C easier.  //C is case sensitive, whereas ""FreeBASIC"" normally is not.//

%%(freebasic)
'' mylib1.bas

function Add2Numbers cdecl alias "Add2Numbers" _
	( _
		byval x as integer, _
		byval y as integer _
	) as integer

	return x + y

end function
%%

Create a file called ##mylib1.bas## as above and compile it with:

	##fbc -lib mylib1.bas##.  

This will create our static library ##libmylib1.a##.  Next we need a C program that is going to call the library we just made.  We must add a prototype that exactly matches the function we have in the ""FreeBASIC"" library.  The C listing below is our main entry point, will set up a couple of variables to call ##""Add2Numbers()""##, and print the results.

%%(c)
/* test1.c */

#include <stdio.h>

/* Prototype from libmylib.a */
int Add2Numbers( int x, int y );

int main ()
{
	int a = 5;
	int b = 7;
	int c = Add2Numbers( a, b );

	printf( "a = %d\n", a );
	printf( "c = %d\n", b );
	printf( "a + b = %d\n", c );

	return 0;
}
%%

To compile this C program using the ""FreeBASIC"" library we just made we need to compile ##test1.c## as we normally would but also tell it which libraries are needed.  In our case, it is ##libmylib1.a##.

	##gcc test1.c -L . -l mylib1 -o test1.exe##

The '-L .' option tells the linker to search in the current directory for libraries, and the '-l mylib1' indicates that we want to link with the library we just created.  This is the simplest case becase the libmylib1.a library has no dependencies.  If mylib1.bas needed other libraries, for example the ""FreeBASIC"" run-time library libfb.a, we would need to specify that as well to gcc.


{{anchor name="S2"}}{{fbdoc item="section" value="FreeBASIC Library With Dependencies"}}

Here we create a ""FreeBASIC"" library that uses some features from the ""FreeBASIC"" runtime and graphics library.  In this case we will have to specify any additional needed libraries to GCC.

%%(freebasic)
'' mylib2.bas

sub TestGfx cdecl alias "TestGfx" ()

	screen 12

	line (0,0)-(100,100),15

	sleep

end sub
%%

Create a file called ##mylib2.bas## with the listing above and compile it with:

	##fbc -lib mylib2.bas##.

This will create our static library ##libmylib2.a##.  Next we need a C program that is going to call the library we just made.  We must add a prototype that exactly matches the function we have in the ""FreeBASIC"" library.  This C listing will provide our entry point and just call ##""TestGfx""()## before terminating.

%%(c)
/* test2.c */

void TestGfx();

int main()
{

	TestGfx();

	return 0;

}
%%

To compile and link ##test2.c## directly with ##gcc##, not only do we need to tell ##gcc## that we want to link with ##libmylib2.a##, but also every other library that ##libmylib2.a## needs.

	%%gcc test2.c -L. -lmylib2 -L"C:\FreeBASIC\lib\win32" "C:\FreeBASIC\lib\win32\fbrt0.o" -lfbgfx -lfb -lgdi32 -o test2.exe%%

Depending on what our ""FreeBASIC"" library uses, it we may use several additional libraries, we must specify all the names of the libraries on the ##gcc## command line.  In this example, ""FreeBASIC"" is located in "C:\""FreeBASIC""", but you should specify whatever directory you installed ""FreeBASIC"" to.  "C:\"""FreeBASIC""\lib\win32\fbrt0.o" is a special startup file that will initialize the ""FreeBASIC"" runtime library.  More specifically, it is initialized after the C runtime library, but before any of our program code is called.  The additional ##-lfbgfx##, ##-lfb##, ##-lgdi32##, are the additional libraries needed to complete linking.  The actual libraries will vary depending on which ""FreeBASIC"" runtime functions are used, and which platform, for DOS or Linux, the program is being compiled for.


{{anchor name="S3"}}{{fbdoc item="section" value="Using FreeBASIC as a Smart Linker"}}

""FreeBASIC"" has a neat built-in feature that stores a little bit of extra information in the library indicating what compile time options were used, and which dependent libraries are needed.  This is a ""FreeBASIC"" only feature, so this kind of capability won't be found when using ##gcc## as the main compiler and linker.

If we reuse the examples from the previous section, ##mylib2.bas## and ##test2.c##, but just go about compiling and linking them differently, we can save ourselves a bunch of typing.  Plus we usually won't have to know or remember what our ""FreeBASIC"" built library's dependencies are.  Compile ##mylib2.bas## as before in to a static library.

	##fbc -lib mytest2.bas##

Next we compile our C test program.  Notice the '-c' option for the ##gcc## command line.  This indicates that we are just going to compile the C source, but not link it yet.  ##test2.o## will still have the entry point, but we are going to put it in an object file instead of trying to create an executable right away.

	##gcc -c test2.c -o test2.o##

Lastly, we use ##fbc## to perform the link step.  We are not compiling any basic source files here, but we are going to use the smart linking capabilities of FreeBASIC such that the command line is fairly simple:

	##fbc test2.o -l mylib2##

This will create an executable named ##test2.exe## because ##test2.o## was specified first on the command line.  ""FreeBASIC"" will read the extra information stored in ##libmylib2.a## and automatically know which additional libraries to link with.  That's loads easier than using ##gcc## directly, especially when many extra ""FreeBASIC"" built libraries are needed.


{{fbdoc item="see"}}
	- [[ProPgStaticLibraries|Static Libraries]]

{{fbdoc item="back" value="CommunityTutorials|Community Tutorials"}}