#lang scribble/doc

@begin[(require scribble/manual)
       (require scribble/eval)
       (require scribble/basic)
       (require (for-label (except-in scheme/base exn:fail:syntax struct:exn:fail:syntax make-exn:fail:syntax exn:fail:syntax?)))
       (require (for-label "../main.ss"))
       (require "utils.ss")]

@title[#:tag "intro"]{C Metaprogramming Utilities}

This package provides utilities for manipulating C programs.

@section[#:tag "started"]{Getting Started}

The easiest way to get started using the C metaprogramming utilities is with the main module:

@defmodule/this-package[]

This module provides everything in the entire package. Subsequent sections of this
manual describe the functionality of the individual libraries included, which can also be
required individually.

@;HACK: util.ss hijacks `system-compiler' to avoid actually calling an external process.
@;      It is specially tuned just to answer this one exact query and nothing else.
@examples[#:eval the-eval
          #;(define time.h
            (header
             (struct tm ([int tm_sec]
                         [int tm_min]
                         [int tm_hour]
                         [int tm_mday]
                         [int tm_mon]
                         [int tm_year]
                         [int tm_wday]
                         [int tm_yday]
                         [int tm_isdst]))))
          #;(define time
            (compile-header time.h
                            (system-compiler #:include<> '("time.h") gcc)))
          #;(layout-offset (time 'tm) 'tm_year)]

@section[#:tag "libraries"]{Libraries Provided by this Package}

This package includes:

@itemize[
  @item{A library for parsing C programs--see @secref[]}
  @item{A library for compiling and running C programs with an external compiler--see @secref["eval"]}
  @item{A library for manipulating C syntax--see @secref["syntax"]}
  @item{A library for compiling C header information--see @secref["header"]}
]

@section[#:tag "limitations"]{Known Limitations}

The parser is ad-hoc and handles only a limited subset of C. The AST definition is incomplete.

The parser does not, and likely never will, recognize the C preprocessor.

@section[#:tag "feedback"]{Feedback and Bug Reports}

Before sending feedback or bug reports, please consult the
@link["http://planet.plt-scheme.org/trac/query?status=accepted&status=assigned&status=needinfo&status=new&status=reopened&component=dherman%2Fc.plt&order=priority&col=id&col=summary&col=status&col=type&col=priority&col=milestone&col=component"
      "current set of registered issues"].
If you cannot find your issue there, feel free to
@link["http://planet.plt-scheme.org/trac/newticket?component=dherman/c.plt&owner=dherman"]{file a new bug report}
in the online issue database.

Any other feedback may be emailed to me, Dave Herman, at @link["mailto:dherman@ccs.neu.edu" "dherman@ccs.neu.edu"].

@include-section["history.scrbl"]