NAME

App::AutoBuild - A perl tool to make it quick and easy to compile a C project with automatic compilation of dependencies

VERSION

Version 0.03

SYNOPSIS

Example project layout:

build.pl

        #!/usr/bin/perl
        use App::AutoBuild qw(build shell_config);

        build({
                'cflags'=>[qw(-O2 -Isrc/ -Wall -Wextra), shell_config('sdl-config', '--cflags')],
                'ldflags'=>[qw(-lSDL_image -lm), shell_config('sdl-config', '--libs')],
                'programs'=>{
                        # each output executable goes here.  you can list several.
                        'main'=>'src/main.c',
                },
        });

src/main.c

        #include "stuff.h"

        int main(int argc, char** argv)
        {
                stuff_function();
                return 0;
        }

src/stuff.c

        #include "stuff.h"

        void stuff_function()
        {
                // hai
        }

src/stuff.h

        #pragma once

        void stuff_function();

Note you don't need to put stuff.c into your build.pl-- it Just Works(tm).

An even shorter example-- instead of a build.pl:

build.sh

        #!/bin/sh

        export CC="clang"
        export CFLAGS="-std=c99 -pedantic -Wall -Wextra -O3"

        perl -MApp::AutoBuild -e 'build("main.c");' -- $@

COMMAND LINE

        usage: ./build.pl [-h|--help] [-v] [clean]

                -h, --help: dump help

                -v: increase verbosity (-vv or more -v's)
                        0 (default) only show compile/link actions, in shortened form
                        1 show compile/link actions with full command lines, and at the end a time summary (also shows App::AutoBuild overhead)
                        2 shows debugging for job numbers (not useful really yet)

                -d: increase debugosity (-dd or more -d's)
                        0 (default) nothing!
                        1 show which dependencies caused a recompile
                        2 show stat() calls

                -q: be more quiet

                --cc=(compiler path): pick a compiler other than gcc

                --program=(program): don't compile all targets, just this one

                clean: unlink output files/meta file (.autobuild_meta)

DESCRIPTION

After writing a makefile for my 30th C project, I decided this was dumb and it (the computer) should figure out which object files should be linked in or recompiled. The idea behind this module is you create a build.pl that uses App::AutoBuild and calls build() with cflags and ldflags, an output binary filename, and a C file to start with (usually the C file with main()).

App::AutoBuild will figure out all the object files your C file depends on. A list of included header files (.h) will be computed by GCC and remembered in a cache. At build time, stat() is called on each header file included by your .c file. If any have a different mtime, the .c file will be recompiled. If you include a .h file that has a corresponding .c file, this process repeats and the output object code will be linked into your final binary automatically.

This tool isn't supposed to be a make replacement-- there are plenty of those, and at least one great one already in Perl. The idea is that the build system should know enough about the source code to do what you want for you. This replaces all the functionality of a makefile for a standard C project with the added bonus of having it only link in the objects that are actually used in each output target.

CAVEATS

For this to work properly, you must have a scheme and follow it. Every .c file must have an .h file that matches (with the exception of the .c file with main()). For now, the .c and .h files must be in the same directory (but this may be fixed in the future).

If you have a .h file and an unrelated .c file with the same name (as in, headers.h and headers.c) in the same folder, the .c file will be compiled and linked in automatically. If this doesn't work well for you, put the .h files without .c files into a different folder (i.e. "include/") or something.

A .autobuild_meta file is created in the current directory so it can remember modification times and dependency lists of files. This will definitely be configurable in a future version!

SUBROUTINES/METHODS

These are exported by default.

build()

Pass this function a hashref of parameters for how to build your project. Keys are as follows:

cflags

An arrayref of cflags

ldflags

An arrayref of ldflags

programs

A hashref with binaries as keys, and start-point C files as values.

rules

An arrayref of rule hashrefs. See "RULES".

shell_config()

This is a helper function that takes a shell command + args (as an array) to pass to system() and splits the STDOUT into an array by whitespace.

I do all this as arrays because the CFLAGS/LDFLAGS can be added or removed per-file with rules.

RULES

Rules let you have custom build options per-file. For now it only supports adding/removing cflags for a given .c file, or adding/removing ldflags for a given output binary.

        {'file'=>'contrib/GLee/GLee.c', 'del_cflags'=>['-pedantic']},
        {'file'=>'configtest', 'add_ldflags'=>['-lyaml'], 'del_ldflags'=>['-lGL', '-lGLU', shell_config('sdl-config', '--libs')]},

These definitely need some more work!

AUTHOR

Joel Jensen, <yobert at gmail.com>

BUGS/TODO

Please email me if it doesn't work! I've only tested with GCC and clang.

Job paralellizing would be sweet. Patches welcome.

This doesn't work with C++ yet, or any other languages for that matter. Sometime later!

LICENSE AND COPYRIGHT

Copyright 2010 Joel Jensen.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

cpanm App::AutoBuild

perl -MCPAN -e shell
install App::AutoBuild