[buildstream] 01/05: Add doc/source/main_quickstart.rst

[no...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

not-in-ldap pushed a commit to branch jjardon/getting_started
in repository https://gitbox.apache.org/repos/asf/buildstream.git

commit 69b0058f3abaff906f0e97a5ea84332afbd8e40e
Author: Javier Jardón <jj...@gnome.org>
AuthorDate: Thu Mar 15 22:03:06 2018 +0000

    Add doc/source/main_quickstart.rst
    
    Directly copied from https://wiki.gnome.org/SamThursfield/BuildStreamQuickStart
---
 doc/source/main_quickstart.rst | 77 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 77 insertions(+)

diff --git a/doc/source/main_quickstart.rst b/doc/source/main_quickstart.rst
new file mode 100644
index 0000000..bf93425
--- /dev/null
+++ b/doc/source/main_quickstart.rst
@@ -0,0 +1,77 @@
+:orphan:
+
+.. _main_quickstart:
+
+What is BuildStream?
+====================
+BuildStream is a command-line tool that executes software build and integration pipelines.
+
+It supports a wide range of use cases: currently you can produce Debian packages, 
+Linux virtual machine images, and Flatpak application bundles,
+and it's possible to extend BuildStream through its plugin system to produce any type of 
+output you like.
+
+All builds are performed in a controlled sandbox with an emphasis on reproducibility. 
+In particular, builds are not allowed to do network access within the sandbox.
+This allows build results to be shared between multiple developers.
+
+BuildStream does not mandate that you use any particular automation tool, but builds
+can easily be automated using GitLab CI, Jenkins, BuildBot or with many other tools.
+
+Concepts
+--------
+The bst commandline tool operates within a project and a project contains one or more elements.
+The elements each describe how to build one component from its sources.
+
+Projects can be small or large, and can depend on other BuildStream projects. 
+We recommend keeping each BuildStream project in its own Git repository.
+
+A project is marked by a project.conf file which sets up project-wide configuration options.
+The syntax used is YAML. 
+The directory containing project.conf is considered to be the top-level project directory,
+and you must always run bst commands from this directory.
+
+Elements usually live a subdirectory of the project named elements.
+Each element is represented on disk by a .bst file which again uses YAML syntax.
+An element has various attributes that authors can control, but BuildStream aims to support 
+the "don't repeat yourself" principle and so provide sensible default values are provided that
+should fit many cases.
+
+Here is an example element, which is taken from the Freedesktop SDK project and describes
+how to build the GNU Nano text editor::
+
+  kind: autotools
+  description: GNU nano
+
+  depends:
+    - filename: bootstrap-import.bst
+      type: build
+    - filename: base/pkg-config.bst
+
+  sources:
+    - kind: tar
+      url: http://ftp.gnu.org/gnu/nano/nano-2.8.7.tar.xz
+      ref: fbe31746958698d73c6726ee48ad8b0612697157961a2e9aaa83b4aa53d1165a
+
+You can see at a glance that the upstream source tarball is referenced in the sources section.
+Note that the ref field here stores the SHA256 checksum of the contents of the file,
+which BuildStream uses to validate the tarball after fetching it.
+The source declares that is of kind: tar. BuildStream supports various other types of sources too.
+The list of built-in sources can be found here. Support for more types of source can be added by 
+writing plugins.
+
+There are no build instructions written here because GNU Nano uses a standard build system
+that BuildStream already supports. The first line (kind: autotools) instructs BuildStream
+that it should fill in the build instructions for this element using the autotools element plugin.
+There are various ways to override the defaults which are described in the "Composition"
+section of the reference manual.
+
+The depends section is a little harder to read at a glance. The filenames listed here are
+other elements within the same project. One of these provides the pkg-config tool which is built
+in a similar way. The other provides a binary sysroot which is built as part of a separate project.
+BuildStream runs all builds inside a sandbox without any access to the host, and it doesn't provide
+any standard way of making standard programs like a UNIX Shell available in the sandbox.
+All build commands require various tools to function, at minimal a shell but usually also a C compiler
+and a whole array of other possible tools. It is up to the individual project to provide these,
+and so the first element of a project will normally be an import element that pulls prebuilt
+binaries from somewhere.