The following documents the tools required for compiling and building a CSP plugin. Most of the makefiles in the examples directory use these tools when building the example programs.
CspCompile translates a CSP (HTML file) with embedded C/C++ code into a HttpPage that can be accessed by the Virtual File System. CspLink combines all the data files produced by compiling many CSP files into one large data file. CspLink also generates a C file which contains the offset position and size to all blocks in the data file. The C file must be compiled and linked with your system.
The CspCompiler is typically run via a makefile. The Barracuda SDK includes CspMakeGen, which is a tool that automatically creates a makefile for all CSP pages.
$ CspCompile Usage: cspCompile [flags] [outdir] infile Flags: --cplusplus Generate C++ code --path path strip path from infile --noline Suppress #line directives --output name Output name. Used by CspMakeGen Use --output filename | outdir
| --cplusplus | Use this flag if you use C++ within the server tags. |
| --path | Strips off the first part of the path from the virtual file system -- i.e. strips off the base path. The URL with the path flag=basepath would be: http://dir1/dir2/myPage.html and the URL without the flag would be: http://basepath/dir1/dir2/myPage.html. |
| --noline | The CspCompiler emits C #line directives by default. The #line directive makes it possible for the compiler to generate debug information that refers to the original file and not to the C file generated by CspCompile. A compliant C compiler and C debugger will make it possible to set breakpoints and step the C/C++ code in the CSP file. Most compilers support this flag, but some compilers might get confused by the line directive and you can therefore instruct the CspCompiler to not emit line directives. |
| --output | Change the name of the C/C++ file and the .dat file produced by CspCompile. |
Typical use:
CspCompile --cplusplus –-path basepath obj basepath/dir1/dir2/myPage.html
CspCompile generates a data file which ends with ".dat" for each file it compiles. CspCompile also generates a C file if the compiled file is a HTML file and contains CSP tags -- i.e., contains the <% and %> tags. The C file contains the generated HttpPage service function, and this C file must also be compiled and linked into the application.
CspLink combines all the data files into one large data file. The combined data file, cspPages.dat, contains all of the html files, gifs, etc.. This file is not linked into the application, but accessed through one simple interface. The example directory contains the FileCspReader, which shows how to write such an interface for a file system.
CspLink is typically run via a makefile. The Barracuda SDK includes CspMakeGen, which is a tool that automatically creates a makefile for all CSP pages.
CspLink:
$ CspLink Usage: CspLink [flags] inputfiles Flags: --coutput filename default name is CspPages.c --doutput filename default name is CspPages.dat --init functionName default name is httpInitGeneratedCode
| --doutput | The HTML files, images, etc processed by CspCompile and CspLink go into the cspPages.dat. You can change the name if you generate more than one cspPages.dat. |
| --coutput | The cspPages.c is only generated if you have HTML files with CSP tags. The file contains code for initializing the virtual file system for the code generated by CspCompile and CspLink. The file must be compiled and linked with your application code. |
| --init | This is the name of the function that initializes the virtual file system generated by CspLink. void httpInitGeneratedCode(HttpDir* parent, CspReader* data); You must externally declare and call this function in your web-server startup code. You can change the name if you generate more than one cspPages.c. |
Typical use:
CspLink *.dat
(Auto generated makefiles)
The concept behind CspCompile and CspLink is that you run CspCompile for each "html/shtml" file you want added to the Virtual File System. The output from CspCompile is always one data file and one C file if the HTML file contains CSP tags.
The output name is a combination of filename, extension, and a hash value. The hash value is computed from the directory name and makes sure the output name is unique even if two input files from two separate directories have the same name.
It is, for this reason, tedious to write a makefile for the auto generated data and C files. The CspMakeGen script simplifies this. The script traverses into a given directory and generates a dependency entry for all HTML files found.
The CspMakeGen in the bin directory is a Lua script. The bin directory also contains a version of the script converted to an executable. For example, on windows: CspMakeGen.exe
$ CspMakeGen
Generate CSP makefile
Usage: CspMakeGen [flags] mkname files
Flags:
--cplusplus Generate C++. Default is C.
--init functionName CspLink Command: default name is httpInitGeneratedCode
See CspLink for more info.
--noline CspCompile Command: Suppress #line directives
--add code Insert into makefile, such as include directives
--lib name Set library name. Default is $(LIBNAME)
mkname is makfile output file name (path + name).
The output makefile name is 'Makefile' if mkname is a directory.
'files' is a list of directories and or files.
A file can be a combination of path:file, where path is the top
directory added to the virtual file system.
| --cplusplus | Use this flag if you use C++ within the server tags. This flag is used by CspCompile. |
| --init | This is the name of the function that initializes the virtual file system generated by CspLink. This flag is used by CspLink. |
| --add | The auto generated makefiles require that you define a number of variables (see table below). Some make programs, such as nmake, handle passing variables from a top makefile poorly. One can instead have all the variables declared in an include makefile. This directive adds the necessary code for including your "rules" makefile. |
See the Makefile in the examples/demo directory for an example on how to use the CspMakeGen tool.
Typical use:
CspMakeGen –-cplusplus obj htmlDir
This will generate a makefile in the obj directory. The auto generated CSP makefile is typically called from a top makefile or from an IDE.
The top makefile must define and export the following symbols before calling the makefile generated by CspMakeGen:
| LIBNAME | The name of the generated library. |
| AR | The archiver/linker. |
| ARFLAGS | The linker flags. The last flag must be the flag for generating the output file. This is with most compilers "-o". |
| CC | The C compiler, if any. Define CC if you use a C compiler. Define CXX if you are using a C++ compiler. |
| CXX | The C++ compiler, if any. |
| COMPFLAGS | Flags to the C/C++ compiler. The last flag must be the flag for generating the output file. This is with most compilers "-o". |
| O | The output extension, normally ".o" except when using MS-Window compilers: ".obj". |
| BINDIR | The path + '/' to the directory containing CspCompile and CspLink. This flag is not needed if the bin directory is in the PATH environment variable. |
The cspPages.c file generated by CspLink contains code for generating a Virtual File System for the compiled HTML files. The file contains one global function:
void httpInitGeneratedCode(HttpDir* parent)
The user must call this function at startup and pass in the parent directory, which can be root or a branch in the Virtual File System.
The code in cspPages.c will automatically create the needed virtual directory structure. The user must create this directory structure manually before calling httpInitGeneratedCode if any overloaded functionality is needed. The httpInitGeneratedCode function will not create the directory structure if already created.
The HttpDir object allows the user to design advanced directory structures that should suit all needs. The user can create and combine HttpDir objects in any order.
(Embedding the CSP/HTML code in the executable)
bin2c is a tool that can convert any binary file to a (large) C array. The C array can be compiled and linked into your firmware.
The data file produced by CspLink can be stored in flash memory and referenced by a CspReader object, but it is sometimes more convenient to embed the data file with the applications executable code. The Barracuda SDK contains a tool that can convert a binary file into a C array. The C file produced by bin2c can be compiled and linked with the application.
$bin2c
Usage: bin2c [flag] [include files] inFile outfile
You can only use one flag.
flags:
-c name Insert a CSP reader.
Name is the CspReader getter function.
-z name Insert a ZIP reader.
Name is the ZipReader getter function.
-Z name Insert a HttpResRdr and ZIP reader.
Name is the HttpResRdr getter function.
-d name Name of the C Data array
The simplest form of code generation is to run:
bin2c cspPage.dat cspPage.dat.c
This will produce a C array with the name "cspPages". You can change the name with the -d flag.
The C array must be connected to a CspReader, and you can either write the code yourself or use the -c flag which will automatically emit code for a CspReader in the code produced.
The command:bin2c -c getCspPageReader cspPage.dat cspPage.dat.c
generates such a CspReader. You load and initialize the CSP Virtual File System branch as follows:
/* httpInitGeneratedCode is generated by CspLink. One can change the * function name with the --init flag. */ extern void httpInitGeneratedCode(HttpDir* parent, CspReader* data); /* Function name getCspPageReader is the name specified with the -c flag */ extern CspReader* getCspPageReader(void); . . /* Populate the virtual file system. Root dir is an instance of HttpDir */ httpInitGeneratedCode(rootDir, getCspPageReader());
The above code installs the CSP as a Virtual File System (VFS) root directory branch. The CSP can be installed into any location in the VFS. You can also install multiple CSP VFS branches.