README.rst 4.48 KB
Newer Older
1 2
About
-----
3

4
.. image:: https://docs.buildstream.build/_static/release.svg
5 6
   :target: https://gitlab.com/BuildStream/buildstream/commits/bst-1.2

7
.. image:: https://docs.buildstream.build/_static/snapshot.svg
8 9
   :target: https://gitlab.com/BuildStream/buildstream/commits/master

10 11 12 13 14
.. image:: https://gitlab.com/BuildStream/buildstream/badges/master/pipeline.svg
   :target: https://gitlab.com/BuildStream/buildstream/commits/master

.. image:: https://gitlab.com/BuildStream/buildstream/badges/master/coverage.svg?job=coverage
   :target: https://gitlab.com/BuildStream/buildstream/commits/master
15

16 17 18
.. image:: https://img.shields.io/pypi/v/BuildStream.svg
   :target: https://pypi.org/project/BuildStream

19 20 21
.. image:: https://app.fossa.io/api/projects/git%2Bgitlab.com%2FBuildStream%2Fbuildstream.svg?type=shield
   :target: https://app.fossa.io/projects/git%2Bgitlab.com%2FBuildStream%2Fbuildstream?ref=badge_shield

22

23 24
What is BuildStream?
====================
25 26
`BuildStream <https://buildstream.build>`_ is a Free Software tool for 
building/integrating software stacks.
27 28 29 30 31
It takes inspiration, lessons and use-cases from various projects including
OBS, Reproducible Builds, Yocto, Baserock, Buildroot, Aboriginal, GNOME Continuous,
JHBuild, Flatpak Builder and Android repo.

BuildStream supports multiple build-systems (e.g. autotools, cmake, cpan, distutils,
32 33
make, meson, qmake), and can create outputs in a range of formats (e.g. debian packages,
flatpak runtimes, sysroots, system images) for multiple platforms and chipsets.
34

35

36 37 38 39 40 41
Why should I use BuildStream?
=============================
BuildStream offers the following advantages:

* **Declarative build instructions/definitions**

42
  BuildStream provides a flexible and extensible framework for the modelling
43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65
  of software build pipelines in a declarative YAML format, which allows you to
  manipulate filesystem data in a controlled, reproducible sandboxed environment.

* **Support for developer and integrator workflows**

  BuildStream provides traceability and reproducibility for integrators handling
  stacks of hundreds/thousands of components, as well as workspace features and
  shortcuts to minimise cycle-time for developers.

* **Fast and predictable**

  BuildStream can cache previous builds and track changes to source file content
  and build/config commands. BuildStream only rebuilds the things that have changed.

* **Extensible**

  You can extend BuildStream to support your favourite build-system.

* **Bootstrap toolchains and bootable systems**

  BuildStream can create full systems and complete toolchains from scratch, for
  a range of ISAs including x86_32, x86_64, ARMv7, ARMv8, MIPS.

66

67 68
How do I use BuildStream?
=========================
69
Please refer to the `documentation <https://docs.buildstream.build>`_
70
for  information about installing BuildStream, and about the BuildStream YAML format
71
and plugin options.
72

73

74 75 76 77
How does BuildStream work?
==========================
BuildStream operates on a set of YAML files (.bst files), as follows:

78 79
* Loads the YAML files which describe the target(s) and all dependencies.
* Evaluates the version information and build instructions to calculate a build
80
  graph for the target(s) and all dependencies and unique cache-keys for each
81 82 83 84 85
  element.
* Retrieves previously built elements (artifacts) from a local/remote cache, or
  builds the elements in a sandboxed environment using the instructions declared
  in the .bst files.
* Transforms/configures and/or deploys the resulting target(s) based on the
86
  instructions declared in the .bst files.
87

88

89 90
How can I get started?
======================
91
To get started, first `install BuildStream by following the installation guide
92
<https://buildstream.build/install.html>`_
93
and then follow our tutorial in the
94
`user guide <https://docs.buildstream.build/main_using.html>`_.
95 96

We also recommend exploring some existing BuildStream projects:
97 98 99 100 101 102

* https://gitlab.gnome.org/GNOME/gnome-build-meta/
* https://gitlab.com/freedesktop-sdk/freedesktop-sdk
* https://gitlab.com/baserock/definitions

If you have any questions please ask on our `#buildstream <irc://irc.gnome.org/buildstream>`_ channel in `irc.gnome.org <irc://irc.gnome.org>`_
103 104 105 106


Availability in distros
=======================
107 108
* BuildStream:

109 110
.. image:: https://repology.org/badge/vertical-allrepos/buildstream.svg
   :target: https://repology.org/metapackage/buildstream/versions
111 112 113 114 115

* BuildStream external plugins (bst-external)

.. image:: https://repology.org/badge/vertical-allrepos/bst-external.svg
   :target: https://repology.org/metapackage/bst-external/versions