docs/development.rst

=============
 Development
=============

This document contains information on developing llbuild.

The project is set up in the following fashion, generally following the LLVM and
Swift conventions.

* For C++ code:

  * The code is written against the C++14 standard.

  * The style should follow the LLVM conventions, but variable names use
    camelCase.

  * Both exceptions and RTTI are **disallowed**.


* Dependencies:

  * llbuild depends on having a C++14 compatible compiler (although
    we do maintain some workarounds to support older versions of GCC/libstdc++
    that were not fully compliant).

  * llbuild depends on having `lit` and `FileCheck` available for executing our
    tests. Currently, the CMake system requires that these dependencies be
    satisfied to complete.


* The project is divided into conceptually distinct layers, which are organized
  into distinct "libraries" under `lib/`. The current set of libraries, and
  their dependencies, is:

  **llvm**

    Shared LLVM support facilities, for llbuild use. These are intended to be
    relatively unmodified versions of data structures which are available in
    LLVM, but are just not factored in a way that we can use them. The goal is
    to eventually factor out a common LLVM-support infrastructure that can be
    shared.

  **Basic**

    Support facilities available to all libraries.

  **Core**

    The core build engine implementation. Depends on **Basic**.

  **BuildSystem**

    The "llbuild"-native build system library. Depends on **Basic**, **Core**.

  **Ninja**

    Programmatic APIs for dealing with Ninja build manifests. Depends on
    **Basic**.

  **Commands**

    Implementations of command line tool frontends. Depends on **BuildSystem**,
    **Core**, **Ninja**.

  Code in libraries in the lower layers is **forbidden** from using code in the
  higher layers.

* Public facing products (tools and libraries) are organized under
  `products/`. Currently the products are:

  **llbuild**

    The implementation of the command line `llbuild` tool, which is used for
    command line testing.

  **libllbuild**

    A C API for llbuild.

  **swift-build-tool**

    The command line build tool used by the Swift package manager.

* Examples of using `llbuild` are available under `examples/`.

* There are two kinds of correctness tests include in the project:

  **LLVM-Style Functional Tests**

    These tests are located under `tests/` and then layed out according to
    library and the area of functionality. The tests themselves are written in
    the LLVM "ShTest" style and run using the `Lit` testing tool, for more
    information see LLVM's [Testing
    Guide](http://llvm.org/docs/TestingGuide.html#writing-new-regression-tests).

  **C++ Unit Tests**

    These tests are located under `unittests/` and then layed out according to
    library. The tests are written using the
    [Googletest](https://code.google.com/p/googletest/) framework.

  All of these tests are run by default (by `lit`) during the build.

* There are also additional performance tests:

  **Xcode Performance Tests**

    These tests are located under `perftests/Xcode`. They use the Xcode XCTest
    based testing infrastructure to run performance tests. These tests are
    currently only supported when using Xcode.

* Header includes are placed in the directory structure according to their
  purpose:

  `include/llbuild/<LIBRARY_NAME>/`

    Contains the *internal* (in Swift terminology) APIs available for use by
    any other code in the *llbuild* project (subject to layering constraints).

    **All** references to these includes should follow the form::

      #include "llbuild/<LIBRARY_NAME>/<HEADER_NAME>.h"

  `lib/llbuild/<LIBRARY_NAME>`

    Contains the *internal* (in Swift terminology) APIs only available for use
    by code in the same library.

    **All** references to these includes should follow the form::

      #include "<HEADER_NAME>.h"

  The Xcode project disables the use of headermaps, to aid in following these
  conventions.