#lang scribble/doc
@require[(planet cce/scheme:4/planet)
scribble/manual
scribble/eval
scribble/basic
"abnf.ss"
"utils.ss"]
@require[(for-label scheme/base
(this-package-in main))]
@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.
@;NOTE: this is completely faked--see the hack in utils.ss.
@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 of abstract syntax for the C99 language--see @secref["syntax"]}
@item{A library for parsing C99 programs--see @secref["parsing"]}
@item{A (preliminary) library providing S-expression syntax for C--see @secref["pc"]}
@item{A library for compiling and running C programs with an external compiler--see @secref["eval"]}
@item{A library for compiling C header information--see @secref["header"]}
]
@section[#:tag "limitations"]{Known Limitations}
The @seclink["parse"]{parser} does not recognize the C preprocessor. I may attempt to implement
the preprocessor in the future, but there's no guarantee at this point.
There is one major known bug in the @seclink["parse"]{parser}: it does not currently recognize the production
@BNF[
(list @nonterm{ParameterDeclaration}
@BNF-seq[@nonterm{DeclarationSpecifiers} @nonterm{AbstractDeclarator}])
]
This production causes a single shift/reduce conflict that I still have to track down.
The @seclink["grammar"]{grammar} does not support any extensions for GCC, MSVC, or any other specific
C implementations. I intend to add support for these extensions on a by-need basis.
Specific requests (as well as patches) are welcome.
@seclink["eval"]{External compilation} is currently limited to GCC. I intend to add support for
additional compilers on a by-need basis;
patches are welcome.
@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"]