Skip to content

hello-world.org

Latest commit

 

History

History
347 lines (289 loc) · 12.2 KB

hello-world.org

File metadata and controls

347 lines (289 loc) · 12.2 KB

Building C++ Hello World

justbuild is a true language-agnostic (there are no more-equal languages) and multi-repository build system. As a consequence, high-level concepts (e.g., C++ binaries, C++ libraries, etc.) are not hardcoded built-ins of the tool, but rather provided via a set of rules. These rules can be specified as a true dependency to your project like any other external repository your project might depend on.

For the remainder of this tutorial, we will use the rules provided in the open-source repository of justbuild, which we assume is checked out to the path /tmp/justbuild.

Setting up the Multi-Repository Configuration

To build a project with multi-repository dependencies, we first need to provide a configuration that declares the required repositories. Before we begin, we need to declare where the root of our workspace is located by creating an empty file ROOT:

$ touch ROOT

Second, we also need to create the multi-repository configuration repos.json in the workspace root:

{ "main": "tutorial"
, "repositories":
  { "just-rules":
    { "repository": {"type": "file", "path": "/tmp/justbuild/rules"}
    }
  , "tutorial":
    { "repository": {"type": "file", "path": "."}
    , "bindings": {"rules": "just-rules"}
    }
  }
}

In that configuration, two repositories are defined:

  1. The "just-rules" repository located at /tmp/justbuild/rules, which contains the high-level concepts for building C/C++ binaries and libraries.
  2. The "tutorial" repository located at ., which contains the targets that we want to build. It has a single dependency, which is the rules that are needed to build the target. These rules are bound via the open name "rules" to the just created repository "just-rules". In this way, the entities provided by "just-rules" can be accessed from within the "tutorial" repository via ["@", "rules", "<module>", "<rule>"].

The final repository configuration contains a single JSON object with the key "repositories" referring to an object of repository names as keys and repository descriptions as values. For convenience, the main repository to pick is set to "tutorial".

Description of the helloworld target

For this tutorial, we want to create a target helloworld that produces a binary from the C++ source main.cpp. To define such a target, create a TARGETS file with the following content:

{ "helloworld":
  { "type": ["@", "rules", "CC", "binary"]
  , "name": ["helloworld"]
  , "srcs": ["main.cpp"]
  }
}

The "type" field refers to the rule "binary" from the module "CC" of the "rules" repository. This rule additionally requires the string field "name", which specifies the name of the binary to produce. Furthermore, at least one input to the binary is required, which can be specified via the target fields "srcs" or "deps". In our case, the former is used, which contains our single source file (files are considered targets).

Now, the last file that is missing is the actual source file main.cpp:

#include <iostream>

int main() {
  std::cout << "Hello world!\n";
  return 0;
}

Building the helloworld target

To build the helloworld target, we need specify it on the just-mr command line:

$ just-mr build helloworld
INFO: Requested target is [["@","tutorial","","helloworld"],{}]
INFO: Analysed target [["@","tutorial","",helloworld"],{}]
INFO: Export targets found: 0 cached, 0 uncached, 0 not eligible for caching
INFO: Discovered 2 actions, 1 trees, 0 blobs
INFO: Building [["@","helloworld","","helloworld"],{}].
INFO: Processed 2 actions, 0 cache hits.
INFO: Artifacts built, logical paths are:
        helloworld [b5cfca8b810adc4686f5cac00258a137c5d4a3ba:17088:x]
$

Note that the target is taken from the tutorial repository, as it specified as the main repository in repos.json. If targets from other repositories should be build, the repository to use must be specified via the --main option.

just-mr reads the repository configuration, fetches externals (if any), generates the actual build configuration, and stores it in its cache directory (by default under $HOME/.cache/just). Afterwards, the generated configuration is used to call the just binary, which performs the actual build.

Note that these two programs, just-mr and just, can also be run individually. To do so, first run just-mr with setup and capture the path to the generated build configuration from stdout by assigning it to a shell variable (e.g., CONF). Afterwards, just can be called to perform the actual build by explicitly specifying the configuration file via -C:

$ CONF=$(just-mr setup tutorial)
$ just build -C $CONF helloworld

Note that just-mr only needs to be run the very first time and only once again whenever the repos.json file is modified.

By default, the BSD-default compiler front-ends (which are also defined for most Linux distributions) cc and c++ are used for C and C++ (variables "CC" and "CXX"). If you want to temporarily use different defaults, you can use -D to provide a JSON object that sets different default variables. For instance, to use Clang as C++ compiler for a single build invocation, you can use the following command to provide an object that sets "CXX" to "clang++":

$ just-mr build helloworld -D'{"CXX":"clang++"}'
INFO: Requested target is [["@","tutorial","","helloworld"],{"CXX":"clang++"}]
INFO: Analysed target [["@","tutorial","","helloworld"],{"CXX":"clang++"}]
INFO: Export targets found: 0 cached, 0 uncached, 0 not eligible for caching
INFO: Discovered 2 actions, 1 trees, 0 blobs
INFO: Building [["@","tutorial","","helloworld"],{"CXX":"clang++"}].
INFO: Processed 2 actions, 0 cache hits.
INFO: Artifacts built, logical paths are:
        helloworld [b8cf7b8579d9dc7172b61660139e2c14521cedae:16944:x]
$

Defining project defaults

To define a custom set of defaults (toolchain and compile flags) for your project, you need to create a separate file root for providing required TARGETS file, which contains the "defaults" target that should be used by the rules. This file root is then used as the target root for the rules (i.e., the search path for TARGETS files). In this way, the description of the "defaults" target is provided in a separate file root, to keep the rules repository independent of these definitions.

We will call the new file root tutorial-defaults and need to create a module directory CC in it:

$ mkdir -p ./tutorial-defaults/CC

In that module, we need to create the file tutorial-defaults/CC/TARGETS that contains the target "defaults" and specifies which toolchain and compile flags to use:

{ "defaults":
  { "type": ["CC", "defaults"]
  , "CC": ["cc"]
  , "CXX": ["c++"]
  , "CFLAGS": ["-O2", "-Wall"]
  , "CXXFLAGS": ["-O2", "-Wall"]
  , "AR": ["ar"]
  , "PATH": ["/bin", "/usr/bin"]
  }
}

To use the project defaults, modify the existing repos.json to reflect the following content:

{ "main": "tutorial"
, "repositories":
  { "just-rules":
    { "repository": {"type": "file", "path": "/tmp/justbuild/rules"}
    , "target_root": "tutorial-defaults"
    , "rule_root": "just-rules"
    }
  , "tutorial":
    { "repository": {"type": "file", "path": "."}
    , "bindings": {"rules": "just-rules"}
    }
  , "tutorial-defaults":
    { "repository": {"type": "file", "path": "./tutorial-defaults"}
    }
  }
}

Note that the "defaults" target uses the rule ["CC", "defaults"] without specifying any external repository (e.g., ["@", "rules", ...]). This is because "tutorial-defaults" is not a full-fledged repository but merely a file root that is considered local to the "just-rules" repository. In fact, the "just-rules" repository cannot refer to any external repository as it does not have any defined bindings.

To rebuild the project, we need to rerun just-mr (note that due to configuration changes, rerunning only just would not suffice):

$ just-mr build helloworld
INFO: Requested target is [["@","tutorial","","helloworld"],{}]
INFO: Analysed target [["@","tutorial","","helloworld"],{}]
INFO: Export targets found: 0 cached, 0 uncached, 0 not eligible for caching
INFO: Discovered 2 actions, 1 trees, 0 blobs
INFO: Building [["@","tutorial","","helloworld"],{}].
INFO: Processed 2 actions, 0 cache hits.
INFO: Artifacts built, logical paths are:
        helloworld [487dc9e47b978877ed2f7d80b3395ce84b23be92:16992:x]
$

Note that the output binary may have changed due to different defaults.

Modeling target dependencies

For demonstration purposes, we will separate the print statements into a static library greet, which will become a dependency to our binary. Therefore, we create a new subdirectory greet with the files greet/greet.hpp:

#include <string>

void greet(std::string const& s);

and greet/greet.cpp:

#include "greet.hpp"
#include <iostream>

void greet(std::string const& s) {
  std::cout << "Hello " << s << "!\n";
}

These files can now be used to create a static library libgreet.a. To do so, we need to create the following target description in greet/TARGETS:

{ "greet":
  { "type": ["@", "rules", "CC", "library"]
  , "name": ["greet"]
  , "hdrs": ["greet.hpp"]
  , "srcs": ["greet.cpp"]
  , "stage": ["greet"]
  }
}

Similar to "binary", we have to provide a name and source file. Additionally, a library has public headers defined via "hdrs" and an optional staging directory "stage" (default value "."). The staging directory specifies where the consumer of this library can expect to find the library’s artifacts. Note that this does not need to reflect the location on the file system (i.e., a full-qualified path like ["com", "example", "utils", "greet"] could be used to distinguish it from greeting libraries of other projects). The staging directory does not only affect the main artifact libgreet.a but also it’s runfiles; hence, the public header will be staged to "greet/greet.hpp". With that knowledge, we can now perform the necessary modifications to main.cpp:

#include "greet/greet.hpp"

int main() {
  greet("Universe");
  return 0;
}

The target "helloworld" will have a direct dependency to the target "greet" of the module "greet" in the top-level TARGETS file:

{ "helloworld":
  { "type": ["@", "rules", "CC", "binary"]
  , "name": ["helloworld"]
  , "srcs": ["main.cpp"]
  , "deps": [["greet", "greet"]]
  }
}

Note that there is no need to explicitly specify "greet"’s public headers here as the appropriate artifacts of dependencies are automatically added to the inputs of compile and link actions. The new binary can be built with the same command as before (no need to rerun just-mr):

$ just-mr build helloworld
INFO: Requested target is [["@","tutorial","","helloworld"],{}]
INFO: Analysed target [["@","tutorial","","helloworld"],{}]
INFO: Export targets found: 0 cached, 0 uncached, 0 not eligible for caching
INFO: Discovered 4 actions, 2 trees, 0 blobs
INFO: Building [["@","tutorial","","helloworld"],{}].
INFO: Processed 4 actions, 0 cache hits.
INFO: Artifacts built, logical paths are:
        helloworld [2b81e3177afc382452a2df9f294d3df90a9ccaf0:17664:x]
$

To only build the static library target "greet" from module "greet", run the following command:

$ just-mr build greet greet
INFO: Requested target is [["@","tutorial","greet","greet"],{}]
INFO: Analysed target [["@","tutorial","greet","greet"],{}]
INFO: Export targets found: 0 cached, 0 uncached, 0 not eligible for caching
INFO: Discovered 2 actions, 1 trees, 0 blobs
INFO: Building [["@","tutorial","greet","greet"],{}].
INFO: Processed 2 actions, 2 cache hits.
INFO: Artifacts built, logical paths are:
        greet/libgreet.a [83ed406e21f285337b0c9bd5011f56f656bba683:2992:f]
      (1 runfiles omitted.)
$