README

This is the source code for cfunctions. Cfunctions makes C header
files from C source code files. For example

    cfunctions example.c

creates a file called "example.h" which contains function declarations
from example.c.

DESCRIPTION

Cfunctions is a C program which reads C files and makes header files
containing the function declarations of the programs in them. For
example, if you have a C file called "example.c" containing a function

     int myfunction (int i, char * s)
     {
          printf ("%s: %d.\n", s, i);
     }

then when you run cfunctions on it, it generates a file called
"example.h" containing

     int myfunction (int i, char * s);

* Global variables

If "example.c" also contains global variables, it makes declarations
for those. For example,

     int myglobal = 999;

becomes

     extern int myglobal;

in "example.h".

* Wrapper

Cfunctions adds a C preprocessor wrapper around the output, a sequence
of instructions of the following form:

    #ifndef CFH_EXAMPLE_H
    #define CFH_EXAMPLE_H
    /* content */
    #endif /* CFH_EXAMPLE_H */

* Verbatim copying

Parts of the C file can be copied verbatim into the C header file
using the format "#ifdef HEADER":

    #ifdef HEADER

    struct xyz { int a; int b; };

    #endif

These will not be compiled in your original code because of the #ifdef
block around them.

* Backups

If there is an existing file called "example.h", then Cfunctions
renames it to "example.h.~1~". If there are existing files called
names like "example.h.~n~" then cfunctions renames "example.h" to
"example.h.~n+1~", where n is the highest number.

If there is an existing file called "example.h", and after running
cfunctions, the output of cfunctions is identical to the previous
"example.h", cfunctions deletes the new file, and renames
"example.h.~1~" back to "example.h". This prevents the unnecessary
recompilation of files which depend on "example.h".

If cfunctions did not do this, supposing your project's Makefile had
rules like

    example.o: example.c example.h
    	    cc -o example.o example.c

    other.o: other.c example.h
    	    cc -o other.o other.c

    example.h: example.c
    	    cfunctions example.c

then each time "example.c" was altered, even if the function
prototypes in it had not been altered at all, example.h's timestamp
would be altered, and make would do an unnecessary recompilation of
"other.c". This can turn into a big waste of time for projects with a
lot of files.

INSTALLATION

To install cfunctions, clone the git repository and compile the
software. You need to have "make" and "flex" to build this
software. "flex" is the software found here:

https://github.com/westes/flex

It is not the software from Adobe Systems with the same name.

The Makefile supplied with the git repository works with BSD make and
Gnu make.

Before compiling cfunctions, edit the files "config.h" and "Makefile"
so that the macros point to appropriate locations in your system.

The command "make" will build a working version of cfunctions in the
current directory. The command "make install" will install it into the
directories you chose when you edited "config.h" and "Makefile".

TESTING

To test cfunctions, run the command "make test" in the top
directory. You probably do not need to run these tests unless you have
extensively altered the source code.

The test script is written in the Perl programming language. Perl can
be obtained from www.perl.org. For installation instructions for a
Unix-like operating system, see

    https://www.lemoda.net/perl/unix-install/index.html

In addition to Perl, the test script also uses some Perl libraries
which you may need to install. The easiest way to install these is to
do as follows:

    curl -L https://cpanmin.us | perl - App::cpanminus
    cpanm IPC::Run3 File::Slurper C::Utility

SUPPORT

Bug reports go here:

   https://github.com/benkasminbullock/cfunctions/issues

If you don't want to make a github account, then email me at
benkasminbullock@gmail.com.

There is currently no documentation beyond this README document. If
you have a question which is not covered in this README, you can
either send email or ask at the bug report page.

SEE ALSO

* Makeheaders

Makeheaders is a C and C++ header file generator. More information may
be found at the following URL:

    http://www.hwaci.com/sw/mkhdr/

HISTORY

I started Cfunctions as a general purpose header file making utility
for C programmers back in the 1990s. It did not prove successful or
gain much traction. However, as of 2017, I use cfunctions very
extensively. The current version of cfunctions is a stripped-down
version of the original general-purpose program which just does the
single job which I need it for.

If you need something much more general purpose than the current
cfunctions, you can find a more full-featured version of the code in
the git repository's history. 

https://github.com/benkasminbullock/cfunctions/commits/master

It also includes a manual page and Gnu info formatted documentation.

Regrettably I cannot offer support with the old versions. The old
versions had many different options, supported a lot of different
formats, were very complicated, and consequently had many bugs. I have
deliberately removed the complex features to reduce the amount of
maintenance required.

If you are a user of previous versions of cfunctions, the current
cfunctions is equivalent to the following options, switched on
permanently:

    cfunctions -i -n -c

The other options, including the debugging options, have all been
removed from the current version of the cfunctions code.

ACKNOWLEDGEMENTS

Egil Kvaleberg from Norway did some work on this project in the 1990s.

AUTHOR, COPYRIGHT AND LICENCE

Cfunctions is copyright Ben Bullock 1998-2017.

Cfunctions is licensed under the GNU General Public Licence, version 2.

See https://www.gnu.org/licenses/old-licenses/gpl-2.0.html