CAKE(1)				 User Commands			       CAKE(1)



NAME
       cake - a C and C++ build tool that requires almost no configuration.

SYNOPSIS
       cake [compilation args] filename.cpp [app args]

DESCRIPTION
       cake generates and runs C and C++ executables with almost no configura-
       tion. To build a C or C++ program,  type	 "cake	filename.c"  or	 "cake
       filename.cpp".	Cake  uses the header includes to determine what other
       implementation (c,cpp) files are also required to be built  and	linked
       against.	  Cake also recognises that developers need to build different
       variants of the same executable.	 A variant is defined to be a compiler
       and  optimisation  combination.	Examples of variants are gcc46_release
       and clang_debug.

   Source annotations:
	      Embed these magic comments in your hpp and  cpp  files  to  give
	      cake instructions on compilation and link flags.

       //#CXXFLAGS=<flags>
	      Appends the given options to the compile step.

       //#LINKFLAGS=<flags>
	      Appends the given options to the link step

       //#GCC44_CXXFLAGS=<flags>
	      Appends the given options to the compile step when building with
	      gcc 4.4.

       //#GCC44_LINKFLAGS=<flags>
	      Appends the given options to the link step  when	building  with
	      gcc 4.4

	      If  no  variant  specific annotations are found, then the global
	      variants are also searched. This allows default behaviour to  be
	      specified, while allowing for a particular variant as well.

   Environment:
	      Environment  variables  can  also be set, from lowest to highest
	      priority, in /etc/cake.conf, ~/.cake.conf	 or  directly  in  the
	      shell.

       CAKE_DEFAULT_VARIANT
	      Sets  the	 default variant to use if --variant=<some variant> is
	      not specified on the command line

       CAKE_<variant>_ID
	      Sets the prefix to the embedded source  annotations  and	prede-
	      fined build macro.

       CAKE_<variant>_CPP
	      Sets the C preprocessor command.

       CAKE_<variant>_CC
	      Sets the C compiler command.

       CAKE_<variant>_CXX
	      Sets the C++ compiler command

       CAKE_<variant>_LINKER
	      Sets the linker command.

       CAKE_<variant>_CPPFLAGS
	      Sets  the	 preprocessor  flags  for  all	c and cpp files in the
	      build.

       CAKE_<variant>_CFLAGS
	      Sets the compilation flags for all c files in the build.

       CAKE_<variant>_CXXFLAGS
	      Sets the compilation flags for all cpp files in the build.

       CAKE_<variant>_LINKFLAGS
	      Sets the flags used while linking.

       CAKE_<variant>_TESTPREFIX
	      Sets the execution prefix used while running unit tests.

       CAKE_<variant>_POSTPREFIX
	      Sets the execution prefix used  while  running  post-build  com-
	      mands.

       CAKE_BINDIR
	      Sets the directory where all binary files will be created.

       CAKE_OBJDIR
	      Sets the directory where all object files will be created.

       CAKE_PROJECT_VERSION_CMD
	      Sets  the command to execute that will return the version number
	      of the project being built. cake then sets a macro equal to this
	      version.

OPTIONS
       --help Shows this message.

       --quiet
	      Doesn’t output progress messages.

       --verbose
	      Outputs the result of build commands (doesn’t run make with -s)

       --cake-debug
	      Output extra cake specific info.

       --config
	      Specify the config file to use.

       --bindir
	      Specifies	 the  directory	 to contain binary executable outputs.
	      Defaults to ’bin’.

       --objdir
	      Specifies the directory to contain  object  intermediate	files.
	      Defaults to ’bin/obj’.

       --generate
	      Only runs the makefile generation step, does not build.

       --build
	      Builds the given targets (default).

       --file-list
	      Print list of referenced files.

       --output=<filename>
	      Overrides the output filename.

       --variant=<vvv>
	      Reads	the	CAKE_<vvv>_CC,	   CAKE_<vvv>_CXXFLAGS	   and
	      CAKE_<vvv>_LINKFLAGS  environment	 variables  to	determine  the
	      build   flags.	Examples   of  variants	 are  debug,  release,
	      gcc44_debug, gcc46_release.

       --static-library
	      Build a static library rather than executable.  This is an alias
	      for --LINKER="ar -src"

       --dynamic-library
	      Build  a	dynamic	 library  rather  than executable.  This is an
	      alias for --append-LINKFLAGS="-shared"

       --ID=<id>
	      Sets the prefix to the embedded source annotations, and a prede-
	      fined macro CAKE_${ID}

       --CPP=<preprocessor>
	      Sets the C preprocessor command.

       --CC=<compiler>
	      Sets the C compiler command.

       --CXX=<compiler>
	      Sets the C++ compiler command.

       --LINKER=<linker>
	      Sets the linker command.

       --CPPFLAGS=<flags>
	      Sets  the	 preprocessor  flags  for  all	c and cpp files in the
	      build.

       --CFLAGS=<flags>
	      Sets the compilation flags for all c files in the build.

       --CXXFLAGS=<flags>
	      Sets the compilation flags for all cpp files in the build.

       --LINKFLAGS=<flags>
	      Sets the flags used while linking.

       --TESTPREFIX=<cmd>
	      Runs  tests  with	 the  given  prefix,  eg.  "valgrind   --quiet
	      --error-exitcode=1"

       --POSTPREFIX=<cmd>
	      Runs post execution commands with the given prefix, eg. "timeout
	      60"

       --append-CPPFLAGS=...
	      Appends the given text to the CPPFLAGS already set.   Useful for
	      adding search paths etc.

       --append-CFLAGS=...
	      Appends  the  given  text	 to the CFLAGS already set. Useful for
	      adding search paths etc.

       --append-CXXFLAGS=...
	      Appends the given text to the CXXFLAGS already set.  Useful  for
	      adding search paths etc.

       --append-LINKFLAGS=..
	      Appends  the  given  text	 to the LINKFLAGS already set. Use for
	      example with ‘wx-config --libs‘

       --bindir=...
	      Overrides the directory where binaries are produced.  ’bin/’  by
	      default.

       --project-version-cmd=...
	      Sets  the command to execute that will return the version number
	      of the project being built.

       --include-git-root
	      Walk up directory path to find .git  directory.  If  found,  add
	      path as an include path.	This is enabled by default.

       --no-git-root
	      Disable the git root include.

       --begintests
	      Starts  a	 test  block. The cpp files following this declaration
	      will generate executables which are then run.

       --endtests
	      Ends a test block.

       --beginpost
	      Starts a post execution block. The  commands  given  after  this
	      will  be run verbatim after each build. Useful for running inte-
	      gration tests, or generating tarballs, uploading	to  a  website
	      etc.

       --endpost
	      Ends a post execution block.

EXAMPLES
       This command-line generates bin/prime-factoriser and bin/frobnicator in
       release mode.  It also generates several tests into the	bin  directory
       and  runs them. If they are all successful, integration_test.sh is run.

	      cake apps/prime-factoriser.cpp apps/frobnicator.cpp --begintests
	      tests/*.cpp --endtests --beginpost ./integration_test.sh --vari-
	      ant=release

       To build a static  library of the get_numbers.cpp file in  the  example
       tests

	      cake --static-library tests/get_numbers.cpp

       To  build  a dynamic library of the get_numbers.cpp file in the example
       tests

	      cake --dynamic-library tests/get_numbers.cpp

OVERVIEW
       cake generates and runs C and C++ executables with almost no configura-
       tion.  To  build	 a  C  or C++ program, type "cake filename.c" or "cake
       filename.cpp".  Cake uses the header includes to determine  what	 other
       implementation  (c,cpp)	files are also required to be built and linked
       against.	 Cake also recognises that developers need to build  different
       variants of the same executable.	 A variant is defined to be a compiler
       and optimisation combination.  Examples of variants  are	 gcc46_release
       and clang_debug.


       Cake  works off the same principles as Ruby on Rails. It will make your
       life easy if you don’t arbitrarily name things. The main rules are:

	      1.  All binaries end up in the bin directory, with the same base
	      name as their source filename.

	      2. The  implementation  file  for	 point.hpp  should  be	called
	      point.cpp.  This	is so cake can compile it and recursively hunt
	      down its dependencies.

	      3. If a header or implementation	file  will  not	 work  without
	      being  linked  with  a  certain  flag, add a //#LINKFLAGS=myflag
	      directly to the source code.

	      4. Likewise,  if	a  special  compiler  option  is  needed,  use
	      //#CXXFLAGS=myflag.

	      5. Minimise the use of "-I" include flags. They make it hard not
	      only for cake to generate dependencies,  but  also  autocomplete
	      tools like Eclipse.

	      6. Only gcc, and linux, is supported. Other tools could be added
	      now, but it’s not what I use.

       Cake also works off a "pull" philosophy of building, unlike the	"push"
       model  of  most	build  processes. Often, there is the monolithic build
       script that rebuilds everything. Users iterate over  changing  a	 file,
       relinking  everything  and  then rerunning their binary. A hierarchy of
       libraries is built up and then linked in to the final executables.  All
       of this takes a lot of time, particularly for C++.

       In  cake,  you only pull in what is strictly necessary to what you need
       to run right now. Say, you are testing a particular  tool  in  a	 large
       project,	 with  a large base of 2000 library files for string handling,
       sockets, etc. There is simply no make file. You might want to create  a
       build.sh for regression testing, but it’s not essential.

       The basic workflow is to simply type:

	      cake app.cpp && ./bin/app

       Only  the  library  cpp files that are needed, directly, or indictly to
       create ./bin/app are actually compiled. If you don’t #include  anything
       that  refers  to	 a  library file, you don’t pay for it. Also, only the
       link options that are strictly needed to generate the app are included.
       Its  possible  to  do in make files, but such fine-level granularity is
       rarely set up in practice, because its too error-prone to do  manually,
       or with recursive make goodness.

HOW IT WORKS
       Cake  uses  "gcc	 -MM  -MF" to generate the header dependencies for the
       main.cpp file you specify at the command line. For each header file, it
       looks for an underlying implementation (c,cpp) file with the same name,
       and adds it to the build. Cake also reads the first 4k of each file for
       special	comments  that	indicate  needed link and compile flags.  Cake
       recurses through the dependencies of the cpp file, and uses  this  spi-
       dering to generate complete dependency information for the application.
       It then lazily generates a makefile, and finally calls make.

MAGIC COMMENTS
       Cake works very differently to other build  systems,  which  specify  a
       hierarchy of link flags and compile options, because cake ties the com-
       piler flags directly to the source code. If you have compress.hpp  that
       requires	 "-lzip"  on  the  link line, add the following comment in the
       first 4K of the header file: //#LINKFLAGS=-lzip

       Whenever the header is included (either directly	 or  indirectly),  the
       -lzip  will  be automatically added to the link step. If you stop using
       the header, for a particular executable, cake will figure that out  and
       not link against it.

       If  you	want  to  compile  a  cpp  file with a particular optimization
       enabled, add, say: //#CXXFLAGS=-fstrict-aliasing

       Because	the  code  and build flags are defined so close to each other,
       its much easier to tweak the compilation locally.

PERFORMANCE
       Because cake generates a makefile to build the C++ file, cake is	 about
       as  fast	 as  a handrolled Makefile that uses the same lazily generated
       dependencies. A typical project takes 0.04 seconds to build if  nothing
       is out of date, versus 2 seconds for, say, Boost.Build.

       Cake  also  eliminates the redundant generation of static archive files
       that a more hierarchical build process  would  generate	as  intermedi-
       aries, saving the cost of running ’ar’.

       Cake  doesn’t build all cpp files that you have checked out, only those
       strictly needed to build your particular binary, so you	only  pay  for
       what  you  use.	You  should see an improvement on most projects, espe-
       cially for incremental rebuilds.

INTEGRATING CAKE WITH A MAKEFILE
       To wrap cake in a Makefile,  use	 dummy	input  targets	that  force  a
       rebuild	every time. Cake is fast so this is fine, it’s just like doing
       a recursive make. This example handles ’make  all’  ’make  test’	 ’make
       clean’ etc.

       all: release debug test
	       cake src/program_to_build.cpp

       release: FORCE
	       cake src/program_to_build.cpp --variant=release

       debug: FORCE
	       cake src/program_to_build.cpp --variant=debug

       test: FORCE
	       cake --begintests test/*.cpp --endtests

       clean: FORCE
	       rm -rf bin

       FORCE:

COMMON ERRORS
       Syntax error: Unterminated quoted string

       This  error can be caused by one of the "magic comments" (i.e., compile
       or link flags) having an unmatched quote.

FILES
       /etc/cake.conf
	      cake configuration file containing the default  CAKE_*  environ-
	      ment variables.

       /usr/bin/cake
	      cake executable

AUTHOR
       cake  was  written  by  Zomojo Pty Ltd.	This manual page was generated
       using help2man.

SEE ALSO
       This  information  is  repeated	in  the cake.1 manual page, README and
       partly in cake --help.



cake 3.0			   May 2013			       CAKE(1)