Introduction

C++ projects can be organized in many ways. Often programmers don't agree on how files should be used, and if directories are needed.

The code seperation mentioned here originates from Large-Scale C++ Software Design by John Lakos, and is also used in the C++ course I followed. So instead of reading this document you could read either that book or follow that course. The course comes with online, free documentation, for more information see below.

There are a lot of pros and cons to this method. I haven't been able to find any con that is strong enough to convince me to switch, so I'll keep organising my projects this way. However, one con was having to script autotools systems and copy Makefile.am files to the class directories, cluttering the project within 3 commands.

Code organisation

Every class has it's own directory. All main programs are part of the root of the src tree (not a prerequisite for ccbuild, but usefull).

Class code

All code for a class is seperated in a directory. It contains a header file with the class header, a internal header file and source files.

The class header contains all declarations for the class and includes only those header files needed for the class interface. It should also have include guards.
The internal header includes the class header and any headers needed by the source files. This way, the internal header becomes a perfact target for header precompilation and you don't have to repeat any includes in you source files.
The source files only include the internal header.

Pros and cons

As you can see, I don't know a lot of cons. This is a purely subjective look, so if you have any cons you think are missing, mail me and this might become objective.

• Using directories
  • PRO Classes become portable between projects.
  • CON Need to enter a directory to open a part of it.
  • CON Need to mention the directory in your include statement.
• Using seperate files per function / functions
  • PRO Compiler load is split, allowing faster builds when updating.
  • PRO Better seperation for distributed/network builds.
  • PRO Work with multiple people on the same class without opening each others files.
  • CON Need to switch files to start editting another function.
  • CON Bootstrapping builds take longer if no internal header precompilation is used.
• Using internal header files
  • PRO Ideal for header precompilation.
  • PRO Keeps your seperate function source files clean.
  • CON Superfluous when using a single source file for your functions.

The course

The course I followed is the C++ course by Frank B. Brokken. This course uses the C++ Annotations as it's main book.

The project organisation mentioned here, and used, is a partial implementation of the practices mentioned in Large-Scale C++ Software Design by Lakos (2001). See 6.5 Header file organization in C++ Annotations.

The general way of working with this is (a) placing classes in directories and (b) placing functions in seperate files. Although Lakos probably wants us to use more global includes and the root of the project in the include path, I currently don't. This may be seen as a handicap of ccbuild at the moment (See: Global ccbuild ), because it can only follow local includes in the right way.

ccbuild's global include neglect

ccbuild doesn't open, scan or search for global include files. This section discusses some of the issues with global includes and the reasoning behind ccbuild's behaviour.

Most projects mix local and global header include statements, however I think this is wrong. Although it is possible to mix these, strict seperation in using local and global include statements isn't a weird standard and is even suggested by the GCC manual. Which states that: local includes should be used for your own program code; and global includes for system header files.

Some people however, think that when they use the local include statement for a file, the system include paths won't searched to find that file. Not true: if a local include cannot be found locally, g++ searches in the path. So, the only difference between global and local is that global explicitly omits seeking files relative to the including file.

You might want to use the include path to shorten your include statements (not having to do ../ all the time), and this can be done using -I on ccbuild, which will automatically be passed on to the compiler. Then ccbuild will also search this path for local includes, and understand what you are talking about (as will te compiler). One reason you might want to do this is because it makes your classes more portable when they don't depend on local headers using relative paths. Although I never had a problem using the, by some seen as ugly, relative paths ("../Otherclass/otherclass.hh").

Now, because most projects wrongly mix global an local header includes, it might be nice if ccbuild could do the same. However, this would a iterative process: resolve global header (where possible), get their -I arguments, add these to the path, loop until all files are found. If you think this won't create a slow process and need this feature, post a feature request.