| |
| ============= |
| Development |
| ============= |
| |
| This document contains information on developing llbuild. |
| |
| Build Instructions |
| ------------------ |
| |
| **Building from source on OSX** |
| |
| * Install latest Xcode and dependencies:: |
| |
| $ brew install cmake ninja |
| |
| * Install FileCheck:: |
| |
| $ brew install llvm |
| |
| * Build:: |
| |
| $ mkdir build && cd build |
| $ cmake -G Ninja -DCMAKE_BUILD_TYPE:=Debug .. |
| $ ninja |
| |
| * If cmake errors out with : `Failed to locate 'lit' executable (missing: LIT_EXECUTABLE)`:: |
| |
| $ export PATH=$HOME/Library/Python/2.7/bin/:"$PATH" |
| |
| and then run cmake or: |
| |
| $ env PATH=$HOME/Library/Python/2.7/bin/:"$PATH" cmake -G Ninja -DCMAKE_BUILD_TYPE:=Debug .. |
| |
| Note: this assumes you have installed `lit` as a user, by running `easy_install --user lit`. |
| |
| **Building from source on Ubuntu** |
| |
| * Install dependencies:: |
| |
| $ sudo apt-get install clang cmake ninja-build sqlite3 python-pip libsqlite3-dev libncurses5-dev |
| |
| * Install lit via pip:: |
| |
| $ sudo pip install lit |
| |
| * Install FileCheck:: |
| |
| $ sudo apt-get install llvm-3.7-tools |
| |
| * Build:: |
| |
| $ mkdir build && cd build |
| $ cmake -G Ninja -DCMAKE_BUILD_TYPE:=Debug -DCMAKE_C_COMPILER:=clang -DCMAKE_CXX_COMPILER:=clang++ .. |
| $ ninja |
| |
| **Building from source on Windows** |
| |
| * Install the latest Visual Studio with Visual C++. |
| |
| * Install the latest version of `CMake <https://cmake.org/>`_ and add `cmake.exe` to the system's PATH |
| environment variable. |
| |
| * Install the latest version of `Ninja <https://ninja-build.org/>`_ and add `ninja.exe` to the system's |
| PATH environment variable. |
| |
| * Configure a developer command prompt, using `amd64` for 64 bit processors and 'x86' for 32 bit processors. |
| All the followingcommands should be executed from a developer command prompt. |
| |
| $ "C:/Program Files (x86)/Microsoft Visual Studio 14.0/VC/vcvarsall.bat" amd64 |
| |
| * Download the latest `sqlite amalgamation source code <https://sqlite.org/download.html>`_ and extract the source code. |
| |
| * Build sqlite3, using `/MDd` for a Debug build, and `/MD` for a Release build:: |
| |
| $ cl shell.c sqlite3.c /MDd -Fe:sqlite3.exe |
| $ lib shell.obj sqlite3.obj /out:sqlite3.lib |
| |
| * Build LLVM, in order to use `FileCheck` and `llvm-lit`. |
| |
| * Build:: |
| |
| $ mkdir build && cd build |
| $ cmake -G "Ninja"^ |
| -DCMAKE_BUILD_TYPE=Debug^ |
| -DLIT_EXECUTABLE="<llvm-bin-directory>/llvm-lit.py"^ |
| -DFILECHECK_EXECUTABLE="<llvm-bin-directory>/FileCheck.exe"^ |
| -DLLBUILD_PATH_TO_SQLITE_SOURCE="<directory-containing-sqlite3.h>"^ |
| -DLLBUILD_PATH_TO_SQLITE_BUILD="<directory-containing-sqlite3.lib>"^ |
| "C:/Users/hbellamy/Documents/GitHub/my-swift/llbuild" |
| $ ninja |
| |
| Notes |
| ----- |
| |
| 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. |