CSP Tools

This page documents the tools used to compile and build CSP pages. Most makefiles in the examples directory use these tools when building the example programs.

CspCompile

CspCompile translates a CSP file, typically an HTML file with embedded C/C++ code, into an HttpPage that can be accessed by the Virtual File System. CspLink combines the data files produced by CspCompile into one larger data file. CspLink also generates a C file that contains the offset and size of each block in the data file. The generated C file must be compiled and linked with your application.

CspCompile is typically run from a makefile. The Barracuda SDK includes CspMakeGen, a tool that automatically creates makefile rules for CSP pages.

CspCompile Command Line:

$ 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

CspCompile Flags:

--cplusplus	Generate C++ code. Use this flag when the server tags contain C++ code.
--path	Strip the base path from the generated virtual path. For example, with `--path basepath`, `basepath/dir1/dir2/myPage.html` becomes `/dir1/dir2/myPage.html` in the Virtual File System. Without the flag, the virtual path includes `/basepath`.
--noline	CspCompile emits C `#line` directives by default. These directives let compilers and debuggers refer back to the original CSP file instead of the generated C/C++ file. Most compilers support this, but if your compiler has problems with `#line`, use `--noline`.
--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 ending in .dat for each file it compiles. CspCompile also generates a C/C++ file when the compiled HTML file contains CSP tags, meaning it contains the <% and %> tags. The generated C/C++ file contains the generated HttpPage service function, and this file must also be compiled and linked into the application.

CspLink

CspLink combines all generated data files into one data file. The combined file, typically cspPages.dat, contains the compiled HTML files, images, and other resources. This file is accessed through a CspReader implementation. The examples include FileCspReader, which shows how to implement a reader for a file system.

CspLink is typically run from a makefile. CspMakeGen can generate the required makefile rules.

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

CspLink flags

--doutput	Set the name of the combined data file. The default is `cspPages.dat`.
--coutput	Set the name of the generated C file. The default is `cspPages.c`. This file is generated when one or more HTML files contain CSP tags, and it must be compiled and linked with your application.
--init	Set the name of the function that initializes the Virtual File System generated by CspLink. `void httpInitGeneratedCode(HttpDir* parent, CspReader* reader);` Declare and call this function from your web server startup code. Change the name when you generate more than one CSP package.

Typical use:

CspLink *.dat

CspMakeGen

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.

For this reason, writing the makefile rules manually is tedious. The CspMakeGen script simplifies this. The script traverses into a given directory and generates a dependency entry for all HTML files found.

CspMakeGen in the bin directory is a Lua script. The bin directory also contains an executable version, for example CspMakeGen.exe on Windows.

$ 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 the makefile 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.

CspMakeGen Flags:

--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 a number of variables (see the table below). Some make programs, such as nmake, handle variable passing from a top-level makefile poorly. You can instead declare all variables in an include makefile. This directive adds the code required to include your rules makefile.

See the Makefile in the examples/demo directory for an example of how to use the CspMakeGen tool.

Typical use:

CspMakeGen --cplusplus obj htmlDir

This generates a makefile in the obj directory. The auto-generated CSP makefile is typically called from a top-level 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 archiver/linker flags. The last flag must be the output-file flag, which is usually `-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 passed to the C/C++ compiler. The last flag must be the output-file flag, which is usually `-o`.
O	The output extension, normally `.o`. Microsoft Windows compilers commonly use `.obj`.
BINDIR	The path, including the trailing slash, to the directory containing CspCompile and CspLink. This variable is not needed if the `bin` directory is in the PATH environment variable.

Installing CSP in the Virtual File System

The cspPages.c file generated by CspLink contains code for initializing the Virtual File System branch for the compiled HTML files. The file contains one global function:

void httpInitGeneratedCode(HttpDir* parent, CspReader* reader)

Call this function at startup and pass in the parent directory plus the CspReader that reads the combined data file. The parent can be the VFS root or any branch in the Virtual File System.

The code in cspPages.c automatically creates the required virtual directory structure. If you need custom directory behavior, create the directory structure manually before calling httpInitGeneratedCode. The generated initialization function does not recreate directories that already exist.

HttpDir lets you design advanced directory structures. You can create and combine HttpDir objects in any order required by the application.

bin2c

Embedding the CSP/HTML data in the executable

bin2c converts a binary file to a C array. The generated 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 in the application's executable code. 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 produces a C array named cspPages. You can change the name with the -d flag.

The C array must be connected to a CspReader. You can write this code yourself or use the -c flag, which emits a CspReader in the generated code.

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. You 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. rootDir is an instance of HttpDir. */
httpInitGeneratedCode(rootDir, getCspPageReader());

The code above installs the CSP package as a Virtual File System branch. The branch can be installed at the VFS root or at any other VFS location. You can also install multiple CSP VFS branches.