README

   1 RcB - rofl0r's C builder.
   2 =========================
   3
   4 builds a C file holding a main method, by checking the headers it includes for
   5 RcB tags.
   6 such a tag might look like
   7
   8 //RcB: DEP "mylib/*.c"
   9 //RcB: LINK "-lSDL"
  10 //RcB: CFLAGS "-std=c99"
  11
  12 the first one tells RcB that the symbols defined in this header can be found
  13 in the listed C files.
  14 after gathering all dependencies, it starts trying to compile the main file,
  15 and analyses the compiler output for which dependencies are not fulfilled.
  16
  17 it then starts multiple passes in which it compiles each referenced C file
  18 into an object file, and scans the symbols it defines.
  19 if those match the missing ones, the file will be added to the list of final
  20 dependencies.
  21
  22 finally if there are no missing deps left, it will link them all together and
  23 create a simple text file containing a list of the required compilation units.
  24 on the next invocation, it will compile the target by simply passing all
  25 required C files to the compiler in one turn.
  26 this is much faster than compiling every C file on its own, and allows to use
  27 the same CFLAGS on all of them, and do nice optimization stuff like
  28 -flto -fwhole-program, which only work really nicely if the compiler gets all
  29 C files in exactly one statement.
  30
  31 RcB tags
  32 --------
  33 //RcB: CMD "param"
  34
  35 "//RcB:" tells rcb that a rcb command starts here, and is treated by the
  36 C compiler as a comment.
  37
  38 currently implemented commands:
  39 DEP     tells rcb to add param to the dependency tree.
  40 LINK    tells rcb to pass param to the compiler (i.e. "-lSDL").
  41         it is advisable to use this only in your main .c file.
  42 CFLAGS  tells rcb to add param to CFLAGS used for compilation.
  43 SKIPON  skip #include directives until SKIPOFF if param can be found inside
  44         CFLAGS.
  45         this is necessary to exclude headers that are conditionally used,
  46         and pull in more deps.
  47         necessary to workaround the fact that rcb doesn't have any means of
  48         preprocessing C code.
  49 SKIPOFF turn off skipping of #include directives if param can be found inside
  50         CFLAGS.
  51 SKIPUON same as SKIPON, but applies to all CFLAGS that are *NOT* found
  52         on the command line.
  53 SKIPUOFF same as SKIPOFF, but applies to all CFLAGS that are *NOT* found
  54         on the command line.
  55
  56
  57 CFLAGS and co
  58 -------------
  59 RcB uses the following environment variables:
  60 RCBFLAGS (can contain one or more rcb command line arguments)
  61 CFLAGS
  62 CC
  63 NM
  64
  65 linking to libraries
  66 --------------------
  67 if you need to link to a specific library, you can pass it to rcb after the
  68 name of the main C file.
  69 just run rcb without arguments to see a list of options.
  70
  71 parallel builds
  72 ---------------
  73 on my wishlist, but currently not possible.
  74 i usually build stuff with ~50 C files, which takes about 10-15 secs.
  75
  76 gotcha's
  77 --------
  78 * by default, rcb uses existing .o files to speed up the process.
  79   however this can lead to some newly added symbols not being found.
  80   in this case use --force to force rcb to recompile everything.
  81
  82 * after renaming or moving stuff around, the information in the .rcb file gets
  83   invalid. use --new to force rcb to remove the rcb file and recollect
  84   dependency information.
  85   NOTE:
  86   it is much safer to use --new than starting to delete .rcb files manually.
  87   if you're in a rush you might erase your c file instead of the rcb file
  88   accidentally.
  89
  90 * after changing some defines, it is advisably to run rcb twice with --force.
  91   the first run will recompile all c files to object files (so that the symbols
  92   can be checked) and link them together,
  93   the second one will then use all the necessary C files for a clean recompile.
  94   this will make sure that the C files will be thrown at the compiler instead
  95   of the object files which may contain/lack (un)wanted code from previous
  96   compilations.
  97
  98 so the rule of thumb is, whenever you run into problems
  99 - check that an rcb tag for your .c file exists
 100 - run rcb with --new and --force, followed by a second run with --force only.
 101 - if the problem persists, add --verbose and inspect which dependendiecs get
 102   pulled in from where.