source tree organization for large-scale C++ projects

M

mshngo

Hi,

I have seen two main methods of organizing the header and source files
in a C++ project. The first method separates the public header files
from the remaining files (i.e., source files and internal/
implementation header files) -- the public header files are usually
stored in a directory named "include", and the remaining files are
stored in another directory named "src". The structures of these two
directories are usually closely related. For example, Postgres adopts
this organization.

The second method does not enforce such a separation -- files are
placed in directories according to which software module they belong
to, so that header files and source files belonging to the same module
will be placed within the same directory.

What are the trade-offs?

Thanks!
Mingsheng
 
I

Ian Collins

mshngo said:
Hi,

I have seen two main methods of organizing the header and source files
in a C++ project. The first method separates the public header files
from the remaining files (i.e., source files and internal/
implementation header files) -- the public header files are usually
stored in a directory named "include", and the remaining files are
stored in another directory named "src". The structures of these two
directories are usually closely related. For example, Postgres adopts
this organization.

The second method does not enforce such a separation -- files are
placed in directories according to which software module they belong
to, so that header files and source files belonging to the same module
will be placed within the same directory.

What are the trade-offs?
I've worked with both and now prefer the latter. My main reason is the
subdirectories can map to namespaces, disambiguating files names.
 
G

Gianni Mariani

mshngo wrote:
....
What are the trade-offs?

Code modularity is sacrificed with the first method. Modularity is
important in large projects.

You somewhat have more work to manage the include paths, however that
can be easily automated. I wrote MakeXS to do just that - automate as
much of the mechanical tasks as I could - making it as easy as dropping
in a file and typing "make".

makexs is now available from Austria C++. http://austria.sourceforge.net/

There are other build systems, cmake for example. MakeXS is still using
make. (gmake to be exact).
 
C

Craig Scott

Hi,

I have seen two main methods of organizing the header and source files
in a C++ project. The first method separates the public header files
from the remaining files (i.e., source files and internal/
implementation header files) -- the public header files are usually
stored in a directory named "include", and the remaining files are
stored in another directory named "src". The structures of these two
directories are usually closely related. For example, Postgres adopts
this organization.

The second method does not enforce such a separation -- files are
placed in directories according to which software module they belong
to, so that header files and source files belonging to the same module
will be placed within the same directory.

What are the trade-offs?

We use the latter option. It makes multi-module projects easier to
manage and allows us to keep headers in the same place as their
contents are implemented. This is also helpful for some text editors
which offer functionality to open an associated source/header file
from the other, but that is a minor usability issue I guess.

You can get some of the advantages of the former option by getting
your build system to "install" public headers to a specific area. We
do this so that we can test the code in a directory structure that is
representative of where the files will be when installed proper. Only
the root of the directory structure changes. This has been a gain for
development since the debug/testing environment is closer to the final
product.
 
J

James Kanze

I have seen two main methods of organizing the header and
source files in a C++ project. The first method separates the
public header files from the remaining files (i.e., source
files and internal/ implementation header files) -- the public
header files are usually stored in a directory named
"include", and the remaining files are stored in another
directory named "src". The structures of these two directories
are usually closely related. For example, Postgres adopts this
organization.
The second method does not enforce such a separation -- files
are placed in directories according to which software module
they belong to, so that header files and source files
belonging to the same module will be placed within the same
directory.
What are the trade-offs?

I presume you're referring to the development code; in delivered
code, the headers are almost always in a separate directory from
the sources, since the sources aren't part of the base
deliverables, and the headers are. (Even if your project is
open source, you don't want users to have to -I on your source
directories---or at least, the users won't want to.) This
argues somewhat for a separation during development as well;
ensure that you're not accidentally including a header which
won't be delivered when you compile your tests, for example.
And having less files in the directories may also improve search
times for the compilers. But such differences are probably
very minor.
 

Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments. After that, you can post your question and our members will help you out.

Ask a Question

Members online

Forum statistics

Threads
473,744
Messages
2,569,479
Members
44,900
Latest member
Nell636132

Latest Threads

Top