My Module Tutorial

HOWto Create BlitzMax Module's, Author Kevin Poole.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

BlitMax allows the user to add new modules to its existing module collection, I will go through the process of the nessersary steps to create and build then make a call using new commands added from our new module. 

Step 1 - Module naming. 
~~~~~~~~~~~~~~~~~~~~~~~

	For the sake of this tutorial we will name are module 'tutorial.mod' first we need to create a folder in blitzmax module directory eg: 'mod\pub.mod' name the created folder 'tutorial.mod'


Step 2 - Module scope and identifier. 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	
	Next run Blitzmax and create a new file, in blitzmax's editor add to the top of the file the module identifier. In this case the identifier is the folder location 'pub' and the file name without the '.mod' surfix we used when we created the new folder in blitzmax module directory. Now to define the modules info We use moduleinfo this allows author and copyright properties to be included in the module.   
	
	
	'
	Module Pub.tutorial

	'
	ModuleInfo "Framework: Module Tutorial"
	ModuleInfo "Author: Kevin Poole"


Step 2 - Code Build and use your module.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

	Rember when creating modules you need to inform blitzmax that you require commands from external module's to do this we use Import. So to use the Print command we would need to inform blitzmax to use brl.basic module, We do this like below.
	
	' brl.basic required to use print command.
	Import brl.basic 

So how would we compile C Source code into our module, this takes a little more explaing. First Download 'MinGW'compiler here:'http://www.mingw.org' install mingw, next we need to set the path variable to include mingw's bin folder. 

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
set MinGW path under window's xp
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

	Right Click My Computer on the desktop, select poperties menu item in the Tabs Advanced now Click the Environment Variables button. scroll down the system variables 
untill you find the path entry. double-click the path entry add the following ';C:\MinGW\bin'
to the end of variable value. rember to use ';' this seperates the path's variables.	

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
set MinGW path under window's 9x
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 

	From the start menu choose run then type 'command.com' this will give you access to the dos prompt, in the prompt type path to get a list of already added path variables. make a note of the list. now open autoexec.bat, add to the open file the path's list including MinGW's bin path ';C:\MinGW\bin' now save the file.

All should be working now so get ready to use some c source code in our module, in your module's folder add the .c source code to be compiled into the module. For the tutorial i called the .c example file 'tutorial_example.c' this example makes 
a call to MessageBox api to show where in the c function.

	#include <windows.h>

	int mod_tutorial_test_c(){
		MessageBox(0,"c function mod_tutorial_test_c","c function mod_tutorial_test_c",MB_OK);
	}

Now back to the module we need to tell blitzmax where using an external function call to do this we need to use the commands Extern and End Extern, with the function names that are in our .c example sourcecode.

	' c source code
	Import "tutorial_example.c"


	' external function calls.
	Extern 
		Function mod_tutorial_test_c:Int()
	End Extern

	So lets look at the final part to this tutorial, what if we want to call a function from within an external .dll then we add to the top of our module source Import using the -l switch. The '.dll' extension is not required when making the import. 

	' thedllfile is the .dll to call function's from within it.
	Import "-lthedllfile"

Use Extern, End Extern and the function from the .dll an example would be like below.

	' external function calls.
	Extern 
		Function My_DLL_test:Int() = "_My_DLL_Test@0"
	End Extern

Were Finished see the example that's along side this tutorial, rember to build your module using bmk.exe found in blitzmax's bin folder. or use keyboard shortcut 'Alt-D' Good luck!