Introduction to the Barracuda Examples

This page explains how the C and C++ examples are organized, how the CSP build tools are used, and how to build the same example either as a host test program or as libraries for an embedded target.

The Barracuda Embedded Web Server is designed in ANSI C. The public header files also include C++ wrappers, so a C++ project can use the C++ API style while the underlying library and examples remain compatible with C builds.

• Understanding the Example Build Structure
• Example Directory Structure
• Building the Example Code
• Building and Running on a Host Computer
• Debugging CSP
• Building for an Embedded Target
• Using the Target Libraries

Understanding the Example Build Structure

The examples use the same basic pattern:

1. CSP files in the csp directory are translated into C source code and linked into a CspPages library.
2. Static resources in the html directory are served through an I/O object such as DiskIo, NetIo, or ZipIo.
3. The application startup code creates an HttpServer, installs the generated CSP pages, installs a resource reader for the static files, and enters the socket dispatcher loop.

The makefiles automate the CSP tool chain. They run the required tools in the bin directory, build the generated CSP code, and create the example libraries or host executable. You can run the tools manually, but using the makefiles is a better starting point because they show the expected build order and generated files.

The generated pages and static files are installed in the Barracuda Virtual File System. In the introduction example, InstallVD.c calls HttpServer_insertCSP for the generated CSP pages and inserts an HttpResRdr for the static resources. To the browser, the CSP directory and HTML directory appear as one URL tree.

When using the standard host build, trace, warning, and error output is written to HttpTrace.txt. The common host startup code is in examples/misc/standalone.

Example Directory Structure

Most C/C++ examples use the following directory layout:

The src directory is meant to be close to target code. Some examples can be used without changes, while others need small platform-specific changes if your target file system, console, threading, or socket setup differs from the host build.

Building the Example Code

The example makefiles can build either a complete host executable or two libraries for target integration:

• CspPages: generated code for the CSP files in the csp directory.
• GLib: the example support code in src plus the I/O support selected by the io= build option.

The makefiles are based on GNU make. Windows users can build with Visual C++ project files or use the command-line makefiles when the required tools are available. The Barracuda CSP tools are included in the bin directory.

You can use these makefiles as templates for your own product build. A production build does not have to use the example makefiles, but it must perform the same logical steps: compile CSP resources, decide how static files are provided, compile the application code, and install the generated pages and resource readers into the Virtual File System.

See CSP Tools for more information about CspMakeGen, CspCompile, CspLink, and the generated files.

Resource I/O Modes

The io= make variable controls how static files and CSP data are made available to the running server:

Building and Running on a Host Computer

The host build is the fastest way to learn an example because it creates a local server executable. The example server listens on port 9357.

Open a command prompt in examples/introduction/make. To display the makefile help, run:

The most useful first build on Linux or another POSIX host is:

For Windows command-line builds that use the native Windows port, use plat=win. Visual C++ users can also open the solution in examples/introduction/VcMake; the Visual C++ project includes a wrapper project that runs the external makefile.

The build=debug option writes output to obj/debug. Start the debug executable from the make directory with:

For a release build, use build=release and run:

The program is a server and normally does not print much after startup. Open http://127.0.0.1:9357 in a browser while the program is running. The address 127.0.0.1 is the loopback address for the local computer.

If you switch between examples that use the same local address and port, clear the browser cache/site data or use a fresh browser profile. The browser can otherwise reuse files or session state from the previous example.

Debugging CSP

CSP files are translated into generated C code. If your compiler and debugger support the C preprocessor #line directive, you can often set breakpoints in the original CSP files and step through the generated logic as if it came from the CSP source.

When debugging a CSP page, build with build=debug, start the server under your debugger, set a breakpoint in one of the files under csp, and then request the matching URL from the browser.

Building for an Embedded Target

Target builds normally use the same example makefile, but build libraries instead of a host executable. The target build produces the generated CSP library and the generic example library, then your product project links those libraries with the Barracuda library and your platform code.

Build for a target by selecting the target platform configuration. You can either use a platform name if one is configured for your environment, or pass a target include file with TINC:

or:

Replace the example TINC path with the Target.mk file for your platform. The build creates the two libraries under the selected object directory, typically:

examples/introduction/obj/release/CspPages.lib
examples/introduction/obj/release/GLib.lib

The exact library prefix and extension depend on the platform toolchain.

Using the Target Libraries

A target application must provide the platform-specific startup around the example code. At minimum, you need to:

• Create a dedicated thread or task for the web server.
• Call the example function barracuda() from that thread. This function is part of the example code, not the Barracuda library.
• Provide or adapt the socket, mutex, thread, and file-system porting layers required by your platform.
• Install an error handler and trace callback similar to the host implementation in examples/misc/standalone/HostInit.c.

The host build uses examples/misc/standalone/Main.c as the program entry point. Embedded systems usually replace this file with RTOS startup code that creates the Barracuda server task.