Changes between Version 4 and Version 5 of user-directories


Ignore:
Timestamp:
Jun 1, 2006 7:37:14 PM (14 years ago)
Author:
andreasw
Comment:

added comment about nomenclature; formatting

Legend:

Unmodified
Added
Removed
Modified
  • user-directories

    v4 v5  
    11= Understanding the Directory Structure =
    22
    3 The directory structure might differ for individual projects in COIN.  However, we recommend to project managers to follow the layout below.  As example we use the {{{Clp}}} project, which requires the {{{CoinUtils}}} project and some data files (to run the unit test program).  We assume here that the base directory has been called {{{Coin-Clp}}} by the user.
     3== Nomenclature ==
    44
    5 If you download the source code for a project (here {{{Clp}}}), you will find the following structure.
     5Here and in the other !BuildTools wiki pages we distinguish between a '''COIN packages''' and a '''COIN project''':
     6
     7 * '''Coin Project''':  With this we mean the files grouped together as one project in COIN.  This contains usually the source code to build a library or a program.  However, in order to actually compile and link this code, it might be necessary to have the files from other COIN projects available.
     8
     9 * '''COIN Package''':  With this we mean all the files that are requires to compile and test the libraries and programs for a particular COIN project.  A COIN package for a COIN project might include other COIN projects, if it depends on those other projects.
     10
     11For 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.
     12
     13== Directory Structure For A COIN Package ==
     14
     15The 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 program) as dependencies.  We assume here that the package base directory has been called {{{Coin-Clp}}} by the user.
     16
     17If you download the source code for a package (here {{{Clp}}}), you will find the following structure.
    618
    719{{{
     
    2840 |
    2941 ----------- MSDevStudio
     42 |
     43 ----------- doxydoc
    3044}}}
    3145
    32 In the base directory of the package ({{{Coin-Clp}}}) 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.
     46In the '''base directory of the package''' ({{{Coin-Clp}}}) 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.
    3347
    34 The {{{BuildTools}}} directory contains files and scripts that are only necessary for project maintainers.  In its subdirectories {{{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.
     48The '''!BuildTools''' directory contains files and scripts that are only necessary for project maintainers.  In its subdirectories {{{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.
    3549
    36 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.
     50Some 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.
    3751
    38 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 [http://projects.coin-or.org/MSDevStudio MSDevStudio home page].
     52If 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 [http://projects.coin-or.org/MSDevStudio MSDevStudio home page].
    3953
    40 For each COIN project that is required to build the desired packages, you will find a subdirectory in the {{{Coin-Clp}}} base directory.  In the main directory for each project (e.g., {{{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 inforation such as a README and AUTHORS file.
     54Also, 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}}}.
    4155
    42 If the project manager of a COIN project follows our suggest directory structure, you will find the following subdirectories in the project's main directory (e.g., in {{{Clp}}} or {{{CoinUtils}}} above):
     56For 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 (e.g., {{{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 inforation such as a README and AUTHORS file.
    4357
    44  * {{{src}}}: Here resides the source code for the package, possibly divided in 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.
     58If 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):
    4559
    46  * {{{inc}}}: If the project is using a configuration header file that 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.
     60 * '''src''': Here resides the source code for the package, possibly divided in 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.
    4761
    48  * {{{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.
     62 * '''inc''': If the project is using a configuration header file that 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.
    4963
    50  * {{{doc}}}: If documetation is provided for this COIN project, it should be found here.
     64 * '''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.
    5165
    52  * {{{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 down to the library.  The source files and further information for this can be found here.
     66 * '''doc''': If documetation is provided for this COIN project, it should be found here.
     67
     68 * '''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 down to the library.  The source files and further information for this can be found here.
    5369
    5470
    55 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 [http://projects.coin-or.org/BuildTools/wiki/user-compile 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.
     71After 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 [http://projects.coin-or.org/BuildTools/wiki/user-compile 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.