wiki:user-directories

Version 9 (modified by rlh, 13 years ago) (diff)

Andreas cleared up some confusion I had on terminology :-)

Understanding the Directory Structure

Nomenclature

Here and in the other BuildTools wiki pages we distinguish between a COIN package and a COIN project:

  • COIN Project: With this we mean the files grouped together as one project in COIN (e.g., source code, Makefiles). In order to actually compile and link libraries and executables associated with the project, it might be necessary to have files that are not contained in the project, e.g., files from other COIN projects (such as CoinUtils).
  • COIN Package: For every COIN project, there is an associated COIN package. A COIN package includes the COIN project along with all the COIN projects it depends on. (Third-party code that is not available on COIN but that is also required to compile the program or library, is not part of the COIN package and has to be downloaded separately.)

For example, to compile the Clp library and solver executable, one needs of course the files from the Clp COIN project. However, as a dependency, we also require the files from the CoinUtils COIN project, as well as a few data files from the Data COIN project to run the test and example programs. Therefore: The Clp COIN Package includes the files from the COIN Projects Clp, CoinUtils, and Data.

Directory Structure For A COIN Package

The directory structure might differ for individual packages in COIN. However, we recommend to project managers to follow the layout below. As example we use the Clp package, which requires the CoinUtils project and some data files (to run the unit test and example programs) as dependencies. We assume here that the package base directory has been called Coin-Clp by the user.

If you download the source code for a package (here Clp), you will find the following structure.

Coin-Clp --- BuildTools
 |            |--- headers
 |
 |---------- Data
 |            |--- Netlib
 |            ---- Samples
 |
 |---------- CoinUtils
 |            |--- src
 |            |--- inc
 |            |--- test
 |            |--- [doc]      ([ ] means currently missing)
 |            ---- [examples]
 |
 |---------- Clp
 |            |--- src
 |            |--- inc
 |            |--- test
 |            |--- [doc]
 |            ---- examples
 |
 ----------- MSDevStudio
 |
 ----------- doxydoc

In the base directory of the package (Coin-Clp, or Clp-x.y.z, depending on how you obtained the code and called this directory) resides the main configuration script and Makefile. A user should only issue commands in this directory. The scripts and Makefiles automatically recurse into the correct subdirectories.

The BuildTools directory contains files and scripts that are only necessary for project maintainers. In its subdirectory headers are versions of the configuration header files with system dependent information (such as availability of certain system header files). On a UNIX-like system, where the configuration script automatically generates the configuration header files for the system it is run on, the files in this directory are not used. However, if one uses other environments to build the COIN binaries (such as the MS Developer Studio), those header files are required.

Some projects require data files, in order to run the unit test program or the provided examples. Those files reside in subdirectories of the Data directory.

If MS Developer Studio workspace and projects files (or similar configuration files) are maintained for the considered package, you will find those in the MSDevStudio subdirectory. For details on this, visit the MSDevStudio home page.

Also, for packages containing C++ code, you will find a doxydoc subdirectory. This contains a configuration script for the doxygen utility, which generates HTML documentation of the source code. Once you have the package configured, you can create this documentation with make doxydox (assuming that you have doxygen installed). The final documentation will be in doxydoc/html.

For each COIN project that is required to build the desired packages, you will find a project subdirectory in the base directory. In the main subdirectory for each project (above CoinUtils and Clp) resides the configuration script for this project, as well as the main Makefile. However, you should not run those configuration scripts from these subdirectories; use the configuration scripts from the base directory instead. In the main directory for each project you find also package-specific information such as a README and AUTHORS file.

If the project manager of a COIN project follows our suggest directory structure, you will find the following subdirectories in the project's main subdirectory (e.g., in Clp or CoinUtils above):

  • src: Here resides the source code for the package, possibly divided into further subdirectories, together with the Makefile to compile the code (which is automatically called from the main Makefile). Note, if you are a user for a COIN library, you should not include the header files from this directory, but instead "install" the package properly and get the headers from the installed include directory.
  • inc: If the project is using a configuration header file, which is automatically generated when you run the configuration script, it is put here. Again, if you are a user for a COIN library, do not include this file from here, but from the installed include directory.
  • test: We ask project maintainers to provide some test program(s) to be able to verify a successful compilation, so that a user can test that everything is working fine, before (s)he installs the libraries and other files. The code and possibly some data files for this unit test are located here.
  • doc: If documetation is provided for this COIN project, it should be found here.
  • examples: A package might contain some source code examples, for example to demonstrate how a user of a library can hook up his/her own code to the library. The source files, an example Makefile, and further information for this can be found here.

After you compiled the code successfully on a UNIX-type system, you can install the package (and automatically all its dependencies), using make install (see the Compilation and Installation page). By default, the files are installed in newly created subdirectories bin, lib, and include in the package's base directory (Coin-Clp above). If you want to install the files at a different location (such as /usr/local), you need to specify the --prefix configure script option.