"Fossies" - the Fresh Open Source Software Archive

Member "firefox-69.0.1/build/docs/tup.rst" (17 Sep 2019, 7543 Bytes) of package /linux/www/firefox-69.0.1.source.tar.xz:


As a special service "Fossies" has tried to format the requested source page into HTML format (assuming markdown format). Alternatively you can here view or download the uninterpreted source code file. A member file download can also be achieved by clicking within a package contents listing on the according byte size field.

Tup Backend

The Tup build backend is an alternative to the default Make backend. The Tup build system is designed for fast and correct incremental builds. A top-level no-op build should be under 2 seconds, and clobbers should rarely be required. It is currently only available for Linux Desktop builds -- other platforms like Windows or OSX are planned for the future.

As part of the mozbuild architecture, the Tup backend shares a significant portion of frontend (developer-facing) code in the build system. When using the Tup backend, ./mach build is still the entry point to run the build system, and moz.build files are still used for the build description. Familiar parts of the build system like configure and generating the build files (the Reticulating splines... step) are virtually identical in both backends. The difference is that mach invokes Tup instead of Make under the hood to do the actual work of determining what needs to be rebuilt. Tup is able to perform this work more efficiently by loading only the parts of the DAG that are required for an incremental build. Additionally, Tup instruments processes to see what files are read from and written to in order to verify that dependencies are correct.

For more detailed information on the rationale behind Tup, see the Build System Rules and Algorithms paper.

Installation

You'll need to install the Tup executable, as well as the nightly rust/cargo toolchain (Note: Replace $topsrcdir with the path to your mozilla-central source tree):

cd ~/.mozbuild && $topsrcdir/mach artifact toolchain --from-build linux64-tup
rustup install nightly
rustup default nightly

Configuration

Your mozconfig needs to describe how to find the executable if it's not in your PATH, and enable the Tup backend:

export TUP=~/.mozbuild/tup/tup
ac_add_options --enable-build-backends=Tup

Configuring Parallel Jobs

To override the default number of jobs run in parallel, set MOZ_PARALLEL_BUILD in your mozconfig:

mk_add_options MOZ_PARALLEL_BUILD=8

What Works

You should expect a Linux desktop build to generate a working Firefox binary from a ./mach build, and be able to run test suites against it (eg: mochitests, xpcshell, gtest). Top-level incremental builds should be fast enough to use them during a regular compile/edit/test cycle. If you wish to stop compilation partway through the build to more quickly iterate on a particular file, you can expect ./mach build objdir/path/to/file.o to correctly produce all inputs required to build file.o before compiling it. For example, you don't have to run the build system in various subdirectories to get generated headers built in the right order.

Currently Unsupported / Future Work

There are a number of features that you may use in the Make backend that are currently unsupported for the Tup backend. We plan to add support for these in the future according to developer demand and build team availability.

Multiple object directories and object directories outside of the source tree

Common workflows involving multiple object directories which may be outside of the source directory are supported by Tup, however there are some things to consider when using these configurations.

Tup builds in automation

Tup builds run on integration branches as Btup in treeherder. There are some aspects of the Tup builds that are currently implemented outside of the make build system, and divergences may cause the Btup job to fail until the build is completely integrated. There are two known situations this has come up.

Partial tree builds in tup

Partial tree builds are possible in tup by invoking ./mach build <relative srcdir path>, however the behavior differs from the make backend. A partial tree build will result in running the commands in Tupfiles in the specified subtree, building .o files and other outputs, but unlike make it will take changed dependencies into account and build everything necessary to update those outputs as well. Also unlike make it will not attempt to find downstream commands that depend on these files, i.e. programs and libraries from other parts of the tree will not be linked. A top level incremental build should be performed to run all commands that depend on changes to the local tree.

How to Contribute

At the moment we're looking for early adopters who are developing on the Linux desktop to try out the Tup backend, and share your experiences with the build team (see Contact).

Contact

If you have any issues, feel free to file a bug blocking buildtup, or contact mshal or chmanchester in #build on IRC.