ccbuild - A strict developer's build utility - Using ccbuild

[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ A ] [ B ] [ next ]

# `ccbuild` - A strict developer's build utility
Chapter 3 - Using `ccbuild`

## 3.1 Organizing your source

`ccbuild` will read your local includes (#include "something") and compile any source next to it into your program or library. For every class you want to use, make sure you create a separate directory. Every directory contains source files which define the different members of your class.

Because every member of a class has it's own file, each of these files will have an approximately equal header. To keep us from typing "using namespace" and "include <iostream>" for each of these files, a so called internal header file is created. The internal header file is the only file the member implementation include and is identified by the extension `.ih`.

An example member implementation is given `fileSystem/touch.cc`:

         #include "fileSystem.ih"

         bool FileSystem::touch(std::string const &filename)
         {
           ofstream file(filename.c_str(), ios::app);
           bool succes = file.is_open();
           file.close();
           return succes;
         }

The internal header file, `fileSystem/fileSystem.ih`:

         #include "fileSystem.hh"
         #include <fstream>

         #include "../options/options.hh"

         using namespace std;
         using namespace bneijt;

The header file defines the `FileSystem` class in the `bneijt` namespace and includes only what is needed for it's declaration.

Splitting the source up like this will get you a lot of files, but will make editing and hacking your code simple. The functions are easy to find, quick to open and easy to grasp. Furthermore, version control software will encounter less collisions and patches will merge more easily on quicker moving code.

The main program is in the root of the source. `ccbuild` has the following listing:

         ./fileSystem/touch.cc
         ./fileSystem/fileSystem.ih
         ./fileSystem/isDirectory.cc
         ./fileSystem/cleanPath.cc
         ./fileSystem/modTime.cc
         ./fileSystem/fileExists.cc
         ./fileSystem/isReadable.cc
         ./fileSystem/absolutePath.cc
         ./ccResolutions
         ./string/replace.cc
         ./string/test.cc
         ./string/string.ih
         ./string/toUpper.cc
         ./string/string.hh
         ./options/options.hh
         ./options/options.ih
         ./options/statics.cc
         ./ccbuild.cc

The top most file is `ccbuild.cc`, which contains a special function: `int main`. `ccbuild` does not care about the arguments the main function takes, but it does care about it being `int main`. This is what `ccbuild` calls a binary target, a file that is the root of a binary.

## 3.2 Building a program

To build a configured `ccbuild` compatible source tree, simple run `ccbuild` in the directory containing the main program. This will compile all programs in the given directory. However, if you only want to compile one given program, issue the command `ccbuild build mainsource.cc`, where mainsource.cc should be the name of the main source file.

Once the command is issued, `ccbuild` will start reading includes the source does and gather sources it should compile. Any sources it can find will be compiled and linked to the main program. Once the `[LINK] mainsource` line get's done, without any errors, your main program will be done and you can start it with `./mainsource`.

## 3.3 Cleaning up

For cleaning your sourcetree, `ccbuild` offers two commands: `clean` and `distclean`. Although they might act almost the same, they are implemented quite different.

The `distclean` command is totally source independent: it does not scan sources, nor look for them. Distclean simply removes all `ccbuild` related file in the "o" directory and all ".gch" files everywhere. If the "o" directory is empty after that, the directory is removed as well.

The `clean` command is much more subtle: it reads the sources and removes any objects part of the current source tree. Because it reads the sources, using clean will only remove those sources part of the given or implied main binary target(s). This command will not remove any directories.

General rule is to use the force command when you want to update everything, use the `clean` when you want to remove all files for a local binary target (but not any other binary targets in the local directory) and use `distclean` to remove everything including old objects and pre-compiled headers.

[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ A ] [ B ] [ next ]

`ccbuild` - A strict developer's build utility