User guide

224 Neuron C Function Libraries
2 The NodeBuilder project manager cannot be used to manage the
dependencies of a library or its component files. Keeping the library up-
to-date is left entirely up to the user.
3 A library can only contain pure C functions and data objects. It cannot
contain or reference Neuron C extensions, such as network variables, I/O
objects, timers, or when statements. The functions documented in the
Neuron C Reference Guide can all be used from a library module as pure
C functions
except the functions that pertain to network variables,
messages, or input/output. Similar use restrictions apply to the Neuron
C built-in variables. See
Performing Neuron C Functions on page 234 for
techniques that you can use to workaround this disadvantage.
4 Any objects from a library that are linked into an application become part
of the application. When the application changes, the library objects are
linked into it again, and their locations could change as a result. In
particular, this means that the objects from a library must be re-loaded
into the device’s memory each time the application is re-linked. This re-
load can be done over the network or by programming some non-volatile
memory device, as appropriate. This disadvantage is presented as a
contrast to Neuron C Custom system images; see Appendix
C, Neuron C
Custom System Images
, on page 227, for more information on this topic.
Library Construction Using the Librarian
You can construct libraries using the stand-alone versions of the Neuron C tools,
as documented in Appendix
A, Neuron C Tools Stand-Alone Use , on page 211.
Use the stand-alone compiler and assembler to compile and assemble the pure C
source files that make up the library. This compilation and assembly process
produces a Neuron object file (.no extension) corresponding to each C source file.
Then, use the nlib.exe Neuron librarian to combine the Neuron object files into a
library that can be used by the Neuron linker.
Following are additional guidelines for constructing libraries:
1 If any symbol in a library module (corresponding to a pure C file) is
referenced, all of that module is included in a link. Therefore, you should
separate unrelated functions to minimize program space use when an
application program uses components of the library.
For example, if you were building a string library containing the strcpy( ),
strcat( ), and strlen( ) functions, you could minimize code space by placing
each function in a separate file, because any given application program
might only want a subset of the functions to be linked in. If all three
functions were placed in a single file, all of them would be linked in any
time any one of them were used.
2 Use the static keyword to declare functions or data items within a library
module that are not to be exposed to the application program or other
library modules. This effectively hides that symbol.
3 Construct include files containing extern function prototypes and extern
data declarations for the users of the library to include in their programs.
You must use the extern keyword for each declaration to allow the
compiler to establish the correct calling sequence and use the appropriate
assembler commands to permit linking to the data object or function
contained in the library.