diff options
author | Tristan Van Berkom <tristan.vanberkom@codethink.co.uk> | 2018-10-19 14:51:13 +0100 |
---|---|---|
committer | Tristan Van Berkom <tristan.vanberkom@codethink.co.uk> | 2018-10-19 14:51:13 +0100 |
commit | 04ee0be53f4b99d563839c886febaf6607d5e325 (patch) | |
tree | 3019b2d6160bd6cdeb6ef7d239c7666e26a4b8c6 | |
parent | 4e3ec89e95955eb3605b7e50b8a35183bbd42be6 (diff) | |
download | buildstream-tristan/mission-statement.tar.gz |
Mission statement in the readmetristan/mission-statement
-rw-r--r-- | README.rst | 141 |
1 files changed, 141 insertions, 0 deletions
diff --git a/README.rst b/README.rst index 9a67dd40c..bb2dc20cf 100644 --- a/README.rst +++ b/README.rst @@ -61,6 +61,147 @@ BuildStream offers the following advantages: a range of ISAs including x86_32, x86_64, ARMv7, ARMv8, MIPS. + + + + + + + + + + + +Mission statement +================= + +* **Deterministic build environment** + + Ideally, the build result (or *artifact*) of any given build will always be + bit-for-bit identical if it is given exactly the same inputs, regardless of + the host environment, so long as BuildStream supports the given host. + + To this end, we go to some lengths to ensure a clean execution environment + for building, and we bump the core cache key version if ever we change or + improve sanitizing of the execution environment, so that everything needs + to be rebuilt. + + While BuildStream cannot itself guarantee a bit-for-bit identical result + for every identical input, we can help in the majority of the work needed + to ensure your builds are determinstic and reproducible. + +* **Reusable build instructions** + + Our declarative format is designed with the intention that the same BuildStream + project can be used to accomplish various things for the set of software it + defines the integration for. + + For instance, using project options; it should be possible to reuse the same + project to deploy the same software stack, or bundle, in various ways and + on various platforms. This should be possible with BuildStream using only some + conditional statements, with minimal redundance and maximum reuse. + +* **Backwards compatibility** + + BuildStream provides various backwards compatible stable API surfaces, in this + way we ensure that nobody's project can ever break as a result of upgrading to + a new version of BuildStream. + + These stable API surfaces include: + + * The command line interface. BuildStream is intended to be scriptable and integratable + into third party tooling. For this reason the command line interface may be extended + from version to version but existing interfaces cannot be modified or removed. + + * The Python plugin facing API surface. In order to avoid breaking anyone's project + who uses a custom or third party plugin, the plugin interfaces may be extended but + can never be modified or removed. + + * The YAML format. As the main API surface for project authors, interfaces can be + extended in the YAML format but never modified or removed. + + Beyond stability of the API surfaces, there is also the stability of the cache + keys. Currently BuildStream guarantees that artifact cache keys will never change + in a given stable release of BuildStream (e.g., all versions of 1.2.x will produce + the same cache key for the same project). + + It is a long term goal to also make artifact cache keys stable, that any later version + of BuildStream produces the same cache key for an artifact which was built by any other + version of BuildStream + +* **Build avoidance** + + It is a general goal to reduce builds as much as possible. Whenever we can + guarantee that we already have a cached artifact which has identical inputs, + we should always prefer the existing artifact. + +* **Convenient developer experience** + + As an integration tool, we place focus on determinism first, but recognize that + developers need to have the same guarantees of determinism as integrators do, but + normally lack the tooling perform edit, compile and test cycles inside a well + defined deterministic build environment. + + BuildStream aims to bring the deterministic and predictable target system + environment to the developer's fingertips, while also bringing convinent + developer tools to the integrator. + +* **Decoupling of tooling and payload** + + BuildStream is a generic build and integration tool which does not make any + assumptions about which software platform or machine architecture is going to + be used. + + Some plugin elements invoking platform specific tooling such as autotools or + cmake, these provide configurable defaults for and are designed with maximum + configurability in mind, while the core application should not become biased + towards specific platforms. + +* **Project Modularity** + + From various experiences with tooling used to produce customized Linux based + appliances, we have recognized a trend that is to combine all build metadata + for the whole stack (from kernel to the user facing applications) in a single + repository, we see this as problematic as it does not allow inter-organizational + knowledge sharing easily, or separation of teams which produce and maintain separate + parts of the operating system stack. + + BuildStream aims to make it easier to produce and maintain systems in a modular + fashion, where organizations or teams can maintain and share parts of the stack. + +* **Easy to use** + + Part of the mission is to be well documented, and as simple and straightforward + to use as possible. + + As a part of this, we place great emphasis on error reporting, and try to fail + as early as possible when we know that we can fail; and provide as much useful + context to the user as possible to allow them to easily figure out what went + wrong. + +* **Core simplicity, maximum flexibility** + + BuildStream aims to be a generic core which simply processes an abstract pipeline + of elements which perform filesystem permutations inside a sandboxed environment. + + We address the problem of scope creep in the following ways: + + - **Many simple tools exposed in the CLI** + + The command line interface is composed mostly of simple commands which + are API stable. + + In this way we allow more complex and user specific constructs to be implemented + as shell scripts which invoke BuildStream one or more times, instead of growing + user specific features directly in the BuildStream CLI. + + - **Stable Plugin API** + + By providing a stable plugin API with strong guarantees that BuildStream will + not break external plugins, we hope to encourage and develop a healthy ecosystem + of useful plugins which users can reliably use in their project. + + How do I use BuildStream? ========================= Please refer to the `documentation <https://buildstream.gitlab.io/buildstream/>`_ |