Creation of an SLL couldn't be easier. All it takes is a single metastatement at the top of your module source code:
#COMPILE SLL
If your source code file is named "ABC.BAS", then your Static Link Library will automatically be named "ABC.SLL". (You can check the #COMPILE section for additional naming options.) When you wish to use the SLL code in a host program, you use:
#LINK "ABC.SLL"
and the contents are automatically embedded in the new .EXE or .DLL. It's just that simple.
A COMMON Sub or Function is one which is visible between the primary host program and one or more SLL unit modules. A Sub/Function is defined as COMMON by inserting that word as one of the descriptors:
FUNCTION MyFunc(Parm AS LONG) COMMON AS DOUBLE
<Function code>...
END FUNCTION
When you create an SLL, you may find you need to reference a Sub or Function which is located in the main Host Module or another SLL. In that case, you must DECLARE it with the COMMON descriptor:
DECLARE FUNCTION MyFunc(Parm AS LONG) COMMON AS DOUBLE
It is not necessary to DECLARE a COMMON Sub or Function at all in the Host Module. If you choose to do so (for self-documentation or other reasons), it is generally advisable to omit the COMMON descriptor, as its presence will force the SLL to be linked, whether needed or not.
Of course, when the host module is compiled, all references to COMMON items must be resolved accurately, or an appropriate error will be generated. Any Sub/Function not defined as COMMON may not be shared between modules.
The EXPORT descriptor identifies a Sub/Function which may be accessed between Dynamic Link Libraries (DLLs), and/or the main executable which links them. If a procedure is not marked EXPORT, it is hidden from these other modules. Generally speaking, it's best not to mark a Sub/Function in an SLL as EXPORT. While it is syntactically acceptable, it may limit your future options when linking the SLL into host modules. PowerBASIC recommends that you mark them as COMMON in the SLL, and add the EXPORT attribute in the host module.
It's easy to create an SLL which can be linked into an executable program or a dedicated DLL for the same purpose. To add the EXPORT attribute to a linked Sub/Function, just add the word EXPORT to the DECLARE statement in the host module or add an #EXPORT metastatement.
#EXPORT MyFunc
DECLARE FUNCTION MyFunc(Parm AS LONG) COMMON EXPORT AS DOUBLE
Using this technique, your SLL can be linked directly into an application executable without publishing the Subs/Functions as EXPORT. However, you can also link the same SLL into a DLL host module which adds the EXPORT attribute to any or all of the COMMON Subs and Functions in the corresponding DECLARE statements.
For example, let's say you want to make a library which publishes the SUB named XXX. You want to provide it in two forms, a linkable SLL and an industry standard DLL. So, first just create the SLL:
#COMPILE SLL = "XXXLib.SLL"
SUB xxx() COMMON
MSGBOX "Hello"
END SUB
Just compile it, and you're ready to link it into your application. But now you want to create a DLL, too, since it might be used with other applications. It's just this easy:
#COMPILE DLL = "XXXLib.DLL"
#EXPORT xxx
#LINK "XXXLib.SLL"
That's all there is to it. You now have an SLL and an equivalent DLL to do the job of the XXX procedure.
A COMMON Class is one which is visible between the primary host module and one or more SLL unit modules. A Class is defined as COMMON by inserting that word as a Class Descriptor:
CLASS MyClass $MyGuid COMMON
<Class code>...
END CLASS
A class which is declared AS COM makes it available to external programs through the COM services of Windows. You can define a class to be both COM and COMMON by adding both descriptors. However, a COM Class is automatically considered to be COMMON as well.
CLASS MyClass $MyGuid COMMON AS COM
<Class code>...
END CLASS
Any code in an SLL marked COMMON, COM, or EXPORT is always included in your compiled SLL module. Any additional code referenced by them is also included. All other unused code is automatically extracted at the time the SLL is compiled. Keep in mind that the resulting SLL module is pre-compiled, and cannot be modified further.
When you link an SLL into a host module, it is examined carefully by the compiler. If it is determined that no code in the SLL is needed, the SLL is simply not linked. This can reduce the size of your final program substantially. However, if even one procedure in an SLL is used, the entire SLL is included. Therefore, it may be in your best interest to split up your code into multiple SLL modules. The PowerBASIC Compiler will pick and choose exactly which ones are needed and ignore the rest. This assures the smallest possible size of the resulting application.
For your convenience, multiple SLL modules may be collected into a Power Library, which is linked as a single item. However, the PowerBASIC Compiler treats the component modules individually, just as though they were each linked separately. A component SLL in a Power Library which is not needed is ignored entirely.
SLL modules are collected into a Power Library with the PowerLib utility librarian. This GUI application can readily add, remove, replace, or list the component SLL modules. Optionally, you can also use a command line librarian if that better serves your needs. The file extension for Power Libraries is ".PBLIB".
See Also