README.rst
1About
2-----
3.. image:: https://gitlab.com/BuildStream/buildstream/badges/master/pipeline.svg
4 :target: https://gitlab.com/BuildStream/buildstream/commits/master
5
6.. image:: https://gitlab.com/BuildStream/buildstream/badges/master/coverage.svg?job=coverage
7 :target: https://gitlab.com/BuildStream/buildstream/commits/master
8
9
10What is BuildStream?
11====================
12BuildStream is a Free Software tool for building/integrating software stacks.
13It takes inspiration, lessons and use-cases from various projects including
14OBS, Reproducible Builds, Yocto, Baserock, Buildroot, Aboriginal, GNOME Continuous,
15JHBuild, Flatpak Builder and Android repo.
16
17BuildStream supports multiple build-systems (e.g. autotools, cmake, cpan, distutils,
18make, meson, qmake), and can create outputs in a range of formats (e.g. debian packages,
19flatpak runtimes, sysroots, system images) for multiple platforms and chipsets.
20
21
22Why should I use BuildStream?
23=============================
24BuildStream offers the following advantages:
25
26* **Declarative build instructions/definitions**
27
28 BuildStream provides a a flexible and extensible framework for the modelling
29 of software build pipelines in a declarative YAML format, which allows you to
30 manipulate filesystem data in a controlled, reproducible sandboxed environment.
31
32* **Support for developer and integrator workflows**
33
34 BuildStream provides traceability and reproducibility for integrators handling
35 stacks of hundreds/thousands of components, as well as workspace features and
36 shortcuts to minimise cycle-time for developers.
37
38* **Fast and predictable**
39
40 BuildStream can cache previous builds and track changes to source file content
41 and build/config commands. BuildStream only rebuilds the things that have changed.
42
43* **Extensible**
44
45 You can extend BuildStream to support your favourite build-system.
46
47* **Bootstrap toolchains and bootable systems**
48
49 BuildStream can create full systems and complete toolchains from scratch, for
50 a range of ISAs including x86_32, x86_64, ARMv7, ARMv8, MIPS.
51
52
53How do I use BuildStream?
54=========================
55Please refer to the `documentation <https://buildstream.gitlab.io/buildstream/>`_
56for information about installing BuildStream, and about the BuildStream YAML format
57and plugin options.
58
59
60How does BuildStream work?
61==========================
62BuildStream operates on a set of YAML files (.bst files), as follows:
63
64* loads the YAML files which describe the target(s) and all dependencies
65* evaluates the version information and build instructions to calculate a build
66 graph for the target(s) and all dependencies and unique cache-keys for each
67 element
68* retrieves elements from cache if they are already built, or builds them in a
69 sandboxed environment using the instructions declared in the .bst files
70* transforms/configures and/or deploys the resulting target(s) based on the
71 instructions declared in the .bst files.
72
73
74How can I get started?
75======================
76The easiest way to get started is to explore some existing .bst files, for example:
77
78* https://gitlab.gnome.org/GNOME/gnome-build-meta/
79* https://gitlab.com/freedesktop-sdk/freedesktop-sdk
80* https://gitlab.com/baserock/definitions
81* https://gitlab.com/BuildStream/buildstream-examples/tree/master/build-x86image
82* https://gitlab.com/BuildStream/buildstream-examples/tree/master/netsurf-flatpak
83
84If you have any questions please ask on our `#buildstream <irc://irc.gnome.org/buildstream>`_ channel in `irc.gnome.org <irc://irc.gnome.org>`_
85
86
