Streaming parser for SCGI requests in C.
C C++
Switch branches/tags
Nothing to show
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
code
demo
help
libs
test
.gitignore
.gitmodules
AUTHORS
CMakeLists.txt
CONTRIBUTORS.txt
LICENSE.txt
README.rst
cscgi-config.cmake

README.rst

cscgi: Streaming SCGI request parser for C.

Authors: André Caron
Contact: andre.l.caron@gmail.com

Description

This library provides a parser for `SCGI`_ requests. The parser is implemented as a finite state machine (FSM) for use in streaming applications (i.e. data arrives at an unpredictable rate and the parser must be interruptible). As such, the parser itself does not buffer any received data. It just forwards it to registered callbacks. It requires little overhead and is well suited for being used in an object-oriented wrapper.

Dependencies

The project relies on cnetstrings to parse SCGI headers.

Getting started

The library is currently only distributed in source form. However, it has a single external dependency and will compile as-is with almost any C compiler.

The following presents the supported way to get up and running with cscgi. Feel free to experiment with your toolchain of choice.

Requirements

Dependencies are:

  1. Git
  2. CMake
  3. Doxygen
  4. A C/C++ compiler toolchain:
    • Microsoft Visual Studio
    • gcc (or g++) and make

Standalone build

  1. Get the source code.

    > git clone git://github.com/AndreLouisCaron/cscgi.git
    > cd cscgi
    > git submodule init
    > git submodule update free to check out a specific version
    
    > git tag
    v0.1
    
    > git checkout v0.1
    
  2. Generate the build scripts.

    > mkdir work
    > cd work
    > cmake -G "NMake Makefiles" ..
    

    The following CMake options are supported:

    1. CSCGI_BUILD_CXX: build C++ wrappers.
    2. CSCGI_BUILD_DEMOS: build demo programs.
    3. CSCGI_BUILD_TESTS: build test programs.
    4. CSCGI_SHARED_LIBS: build cscgi as a shared library (DLL).

    All options are set to ON by default in the standalone builds. Options for demos and tests are ignored and forced to OFF when build as a dependency.

    To change these settings, use the CMake -D command line option. For example, to skip compilation of the demo programs, use this command:

    > cmake -G "NMake Makefiles" .. -DCSCGI_BUILD_DEMOS=OFF
    

    Note that CSCGI_BUILD_CXX must be set to ON to build the demos and tests (they're based on the C++ wrappers).

  3. Build the source code.

    > nmake
    
  4. Run the test suite.

    > nmake /A test
    

    If the CSCGI_BUILD_TESTS option was set to OFF, this will not run any tests.

  5. Build the API documentation.

    > nmake help
    

    Open the HTML documentation in help/html/index.html.

    If Doxygen is not available, this target is not registered so you cannot build the documentation.

Embedded build

  1. Register cscgi and its dependency as Git sub-modules.

    > cd myproject
    > git submodule add git://github.com/AndreLouisCaron/cscgi.git libs/cscgi
    > git submodule add git://github.com/AndreLouisCaron/cnetstring.git libs/cnetstring
    

    Feel free to check out a specific version.

    > cd libs/cscgi
    > git tag
    v0.1
    
    > git checkout v0.1
    > cd ../..
    > git add libs/cscgi
    
  2. Add cscgi targets to your CMake project.

    set(cscgi_DIR
      ${CMAKE_SOURCE_DIR}/libs/cscgi
    )
    set(cnetstring_DIR
      ${CMAKE_SOURCE_DIR}/libs/cnetstring
    )
    
  3. Make sure your CMake project can #include <scgi.h>.

    include_directories(
      ${cscgi_include_dirs}
    )
    include_directories(
      ${cnestring_include_dirs}
    )
    
  4. Link against the scgi library.

    # Note: netstring library is included "${cscgi_libraries}".
    target_link_libraries(my-application ${cscgi_libraries})