Proposed project source and installation directory layout

Post-install layout

Proposal, relative to install location:

bin/
    modcc
    lmorpho
    ...
include/
    arbor/
        util/
        log/
        ...
    .../
lib/
    libarbor.a
    ...
share/mod/
    [built-by-default default NMODL files]
share/data/
    [validation data]
share/doc/
    index.html
    ...

Notes

• lib/ bin/ etc. are placeholders and defaults for possibly user-specified architecture-dependent library and binary installation directories.
• Example executables, validation binaries optionally installed under bin/.
• All code required to link a minimal example, including generated mechanisms for GPU etc., lives in libarbor.a, but extension libraries built on top of arbor can also be installed if they ship with the arbor package.
• Extension library foo will have its public include headers in include/foo.

Open questions

• Where will which parts of the python interfaces reside? How do we ship a package with is compatible with common python installation procedures?
• Keep arbor as our top level include directory and library name, or use arb?
• Should we support installing libarbor as a shared library?

Source/project directory configuration

Relative to project directory:

CMakeLists.txt
cmake/
arbor/
example/
ext/
include/
    arbor/
    arbor/util/
    .../
lmorpho/
modcc/
.../     
test/

• CMake auxillary build scripts live in cmake/.
• Utility library is header-only and public, and lives solely in include/arbor/util/ (see below).
• Top-level peers of the Arbor library have their sources in directories at the top level: modcc, lmorpho (if we ship with this), etc.
• Miniapps get translated into examples that live under example/.
• Any externally-maintained libraries that ship with Arbor live in ext/.
• Some common bodies of code (logging, io support routines) will potentially be used both by libarbor and other code in the package such as modcc; such a collection foo should have public sources in arbor/foo and any public include files in include/arbor/foo.

Reorganization of Arbor library sources.

A tidy-up for post-initial release, and at this point only a proposal:

• Each cell-group kind has its specific source and headers under the one prefix, though one prefix might be shared between more than one cell kind. In particular, all the multi-compartment/FVM cell classes should live under e.g. mccell/.
• All mechanism interfaces for generated code, together with the back-end specific code for executing them should live under mechanism/, and mechanism/<back-end-name>. As far as practical, these should be agnostic to the details of any particular discretization scheme; first non-FVM use case is likely to be single compartment cells with user-specified dynamics.

Inter-source dependencies

While not strictly enforced by the proposed source hierarchy, we should endeavour to keep the inter-dependencies between sub-units of the code clear and strict.

In the following table, units at the same level are not interdependent, but can depend upon anything in a higher level. ‘Library’ is used to indicate a collection of code that need not be built as a library per se.

Tier
0	util (header-only)
1	logging library, I/O utility library, arbor public headers
2	libarbor code, modcc, lmorpho
3	example code, extension libraries

In terms of build system implementation, units of code such as the I/O utilities might be provided within libarbor (if necessary for Arbor functionality), but also linked in directly to executables such as modcc that do not have a dependency on libarbor. This can be achieved with CMake using so-called 'object libraries'. The same approach will reduce the build dependencies for unit tests.