README

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