You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@buildstream.apache.org by no...@apache.org on 2020/12/29 12:37:53 UTC
[buildstream] branch jjardon/getting_started created (now c4da7c9)
This is an automated email from the ASF dual-hosted git repository.
not-in-ldap pushed a change to branch jjardon/getting_started
in repository https://gitbox.apache.org/repos/asf/buildstream.git.
at c4da7c9 main_quickstart.rst: Add links/references to other sections of the docs
This branch includes the following new commits:
new 69b0058 Add doc/source/main_quickstart.rst
new 295bfad source/index.rst: Replace current "Installing" with "Getting started" section
new d3e39b0 Add doc/source/first_project.rst
new 6aba0dd Add doc/source/examples.rst
new c4da7c9 main_quickstart.rst: Add links/references to other sections of the docs
The 5 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
[buildstream] 04/05: Add doc/source/examples.rst
Posted by 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 6aba0ddb43b5e2275c3c12214e088e6301c16184
Author: Javier Jardón <jj...@gnome.org>
AuthorDate: Thu Mar 15 22:29:26 2018 +0000
Add doc/source/examples.rst
---
doc/source/examples.rst | 8 ++++++++
doc/source/index.rst | 1 +
2 files changed, 9 insertions(+)
diff --git a/doc/source/examples.rst b/doc/source/examples.rst
new file mode 100644
index 0000000..6c3f2f3
--- /dev/null
+++ b/doc/source/examples.rst
@@ -0,0 +1,8 @@
+:orphan:
+
+.. _examples:
+
+Examples of projects using BuildStream
+======================================
+* `GNOME Build Metadata <https://gitlab.gnome.org/GNOME/gnome-build-meta/>`_
+* `freedesktop-sdk <https://gitlab.com/freedesktop-sdk/freedesktop-sdk/>`_
diff --git a/doc/source/index.rst b/doc/source/index.rst
index d01c325..89c7829 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -25,6 +25,7 @@ dependencies.
install
docker
first_project
+ examples
.. toctree::
[buildstream] 05/05: main_quickstart.rst: Add links/references to
other sections of the docs
Posted by 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 c4da7c904d1399c9a2ab43d132ea188a7f305232
Author: James Ennis <ja...@codethink.com>
AuthorDate: Mon Mar 19 14:11:40 2018 +0000
main_quickstart.rst: Add links/references to other sections of the docs
---
doc/source/main_authoring.rst | 2 ++
doc/source/main_quickstart.rst | 6 ++----
2 files changed, 4 insertions(+), 4 deletions(-)
diff --git a/doc/source/main_authoring.rst b/doc/source/main_authoring.rst
index 04a968e..4acdc0c 100644
--- a/doc/source/main_authoring.rst
+++ b/doc/source/main_authoring.rst
@@ -58,6 +58,8 @@ Build Elements
* :mod:`pip <elements.pip>` - Pip build element
+.. _sources-section:
+
Sources
~~~~~~~
The following source types are provided with BuildStream:
diff --git a/doc/source/main_quickstart.rst b/doc/source/main_quickstart.rst
index bf93425..f786b0d 100644
--- a/doc/source/main_quickstart.rst
+++ b/doc/source/main_quickstart.rst
@@ -57,14 +57,12 @@ You can see at a glance that the upstream source tarball is referenced in the so
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.
+The list of built-in sources can be found :ref:`here <sources-section>`. 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.
+There are various ways to override the defaults which are described in the :ref:`"Composition" <format_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
[buildstream] 03/05: Add doc/source/first_project.rst
Posted by 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 d3e39b0863b1b1b70e4ef473c08f0736a00205ff
Author: Javier Jardón <jj...@gnome.org>
AuthorDate: Thu Mar 15 22:25:07 2018 +0000
Add doc/source/first_project.rst
This is a minimal example of a bst project done by
Paul Sherwood
---
doc/source/first_project.rst | 80 ++++++++++++++++++++++++++++++++++++++++++++
doc/source/index.rst | 1 +
2 files changed, 81 insertions(+)
diff --git a/doc/source/first_project.rst b/doc/source/first_project.rst
new file mode 100644
index 0000000..d3c5a62
--- /dev/null
+++ b/doc/source/first_project.rst
@@ -0,0 +1,80 @@
+:orphan:
+
+.. _first_project:
+
+Your first project: HelloWorld
+==============================
+
+This is a minimal example of a BuildStream project::
+
+ $ echo "name: Hello.World" > project.conf
+ $ touch hello.world
+ $ cat hello.bst
+ kind: import
+ sources:
+ - kind: local
+ path: hello.world
+ config:
+ source: /
+ target: /
+
+ $ bst build hello.bst
+ [--:--:--][][] START Loading pipeline
+ [00:00:00][][] SUCCESS Loading pipeline
+ [--:--:--][][] START Resolving pipeline
+ [00:00:00][][] SUCCESS Resolving pipeline
+ [--:--:--][][] START Resolving cached state
+ [00:00:00][][] SUCCESS Resolving cached state
+
+ BuildStream Version 1.1.2.dev4+g7fdddf3
+ Session Start: Thursday, 08-03-2018 at 16:53:34
+ Project: Hello.World (/src)
+ Targets: hello.bst
+
+ User Configuration
+ Configuration File: Default Configuration
+ Log Files: /root/.cache/buildstream/logs
+ Source Mirrors: /root/.cache/buildstream/sources
+ Build Area: /root/.cache/buildstream/build
+ Artifact Cache: /root/.cache/buildstream/artifacts
+ Maximum Fetch Tasks: 10
+ Maximum Build Tasks: 4
+ Maximum Push Tasks: 4
+ Maximum Network Retries: 2
+
+ Pipeline
+ buildable b4f6a94f hello.bst
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ [--:--:--][][] START Checking sources
+ [00:00:00][][] SUCCESS Checking sources
+ [--:--:--][][] START Starting build
+ [--:--:--][b4f6a94f][build:hello.bst ] START root/.cache/buildstream/logs/Hello.World/hello/b4f6a94f-build.607.log
+ [--:--:--][b4f6a94f][build:hello.bst ] START Staging sources
+ [00:00:00][b4f6a94f][build:hello.bst ] SUCCESS Staging sources
+ [--:--:--][b4f6a94f][build:hello.bst ] START Caching Artifact
+ [00:00:00][b4f6a94f][build:hello.bst ] SUCCESS Caching Artifact
+ [00:00:00][b4f6a94f][build:hello.bst ] SUCCESS root/.cache/buildstream/logs/Hello.World/hello/b4f6a94f-build.607.log
+ [00:00:00][][] SUCCESS Build Complete
+
+ Pipeline Summary
+ Total: 1
+ Session: 1
+ Fetch Queue: processed 0, skipped 1, failed 0
+ Build Queue: processed 1, skipped 0, failed 0
+
+ $ bst checkout hello.bst my-output
+ [--:--:--][][] START Loading pipeline
+ [00:00:00][][] SUCCESS Loading pipeline
+ [--:--:--][][] START Resolving pipeline
+ [00:00:00][][] SUCCESS Resolving pipeline
+ [--:--:--][][] START Resolving cached state
+ [00:00:00][][] SUCCESS Resolving cached state
+ [--:--:--][][] START Staging dependencies
+ [00:00:00][][] SUCCESS Staging dependencies
+ [--:--:--][][] START Integrating sandbox
+ [00:00:00][][] SUCCESS Integrating sandbox
+ [--:--:--][][] START Checking out files in my-output
+ [00:00:00][][] SUCCESS Checking out files in my-output
+
+ $ ls my-output/
+ hello.world
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 6985ec1..d01c325 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -24,6 +24,7 @@ dependencies.
main_quickstart
install
docker
+ first_project
.. toctree::
[buildstream] 02/05: source/index.rst: Replace current "Installing"
with "Getting started" section
Posted by 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 295bfad9606a0a314339bb5d62d3881557b4f7f4
Author: Javier Jardón <jj...@gnome.org>
AuthorDate: Thu Mar 15 22:10:47 2018 +0000
source/index.rst: Replace current "Installing" with "Getting started" section
---
doc/source/index.rst | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/doc/source/index.rst b/doc/source/index.rst
index fe41a35..6985ec1 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -19,8 +19,9 @@ dependencies.
.. toctree::
:maxdepth: 2
- :caption: Installing
+ :caption: Getting started
+ main_quickstart
install
docker
[buildstream] 01/05: Add doc/source/main_quickstart.rst
Posted by 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.