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 and add cmake.exe to the system’s PATH environment variable.

• Install the latest version of Ninja 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 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.