You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@buildstream.apache.org by gi...@apache.org on 2020/12/29 13:02:03 UTC
[buildstream] branch tiagogomes/docs-improvements created (now
875496d)
This is an automated email from the ASF dual-hosted git repository.
github-bot pushed a change to branch tiagogomes/docs-improvements
in repository https://gitbox.apache.org/repos/asf/buildstream.git.
at 875496d doc: updates considering website being live now
This branch includes the following new commits:
new 3247d22 doc: show an additional level on ToC
new 875496d doc: updates considering website being live now
The 2 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] 02/02: doc: updates considering website being live now
Posted by gi...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
github-bot pushed a commit to branch tiagogomes/docs-improvements
in repository https://gitbox.apache.org/repos/asf/buildstream.git
commit 875496d2c50ecbb9defb964e1c10a66ae0c11b6b
Author: Tiago Gomes <ti...@codethink.co.uk>
AuthorDate: Fri Sep 28 11:24:44 2018 +0100
doc: updates considering website being live now
* Add a link to the website on the main page.
* Remove install instructions as they are now on the website.
* Remove Resources section as that information can be found at the
website, and also looks bad.
* Move artifact server setup from the no longer existing Install section
to the Using section.
---
doc/source/index.rst | 10 +-
doc/source/install_docker.rst | 45 ----
doc/source/install_linux_distro.rst | 30 ---
doc/source/install_source.rst | 289 ---------------------
doc/source/install_versions.rst | 24 --
doc/source/main_install.rst | 29 ---
doc/source/main_using.rst | 1 +
doc/source/release-badge.rst | 26 --
doc/source/snapshot-badge.rst | 26 --
...s.rst => using_configuring_artifact_server.rst} | 6 +-
10 files changed, 6 insertions(+), 480 deletions(-)
diff --git a/doc/source/index.rst b/doc/source/index.rst
index c72489b..c00ac7d 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -13,20 +13,14 @@ They begin with a basic introduction to BuildStream, background
information on basic concepts, and a guide to the BuildStream command line interface.
Later sections provide detailed information on BuildStream internals.
+If you are looking for information about how to install BuildStream,
+please refer to the `BuildStream website <https://buildstream.build>`_.
.. toctree::
:maxdepth: 2
main_about
- main_install
main_using
main_core
CONTRIBUTING
-
-Resources
----------
-* GitLab repository: https://gitlab.com/BuildStream/buildstream
-* Bug Tracking: https://gitlab.com/BuildStream/buildstream/issues
-* Mailing list: https://mail.gnome.org/mailman/listinfo/buildstream-list
-* IRC Channel: irc://irc.gnome.org/#buildstream
diff --git a/doc/source/install_docker.rst b/doc/source/install_docker.rst
deleted file mode 100644
index c1ca7a2..0000000
--- a/doc/source/install_docker.rst
+++ /dev/null
@@ -1,45 +0,0 @@
-
-
-.. _docker:
-
-BuildStream inside Docker
--------------------------
-If your system cannot provide the base system requirements for BuildStream, then it is possible to run buildstream within a Docker image.
-
-The BuildStream project provides
-`Docker images <https://hub.docker.com/r/buildstream/buildstream-fedora>`_
-containing BuildStream and its dependencies.
-This gives you an easy way to get started using BuildStream on any Unix-like
-platform where Docker is available, including Mac OS X.
-
-We recommend using the
-`bst-here wrapper script <https://gitlab.com/BuildStream/buildstream/blob/master/contrib/bst-here>`_
-which automates the necessary container setup. You can download it and make
-it executable like this:
-
-.. code:: bash
-
- mkdir -p ~/.local/bin
- curl --get https://gitlab.com/BuildStream/buildstream/raw/master/contrib/bst-here > ~/.local/bin/bst-here
- chmod +x ~/.local/bin/bst-here
-
-Check if ``~/.local/bin`` appears in your PATH environment variable -- if it
-doesn't, you should
-`edit your ~/.profile so that it does <https://stackoverflow.com/questions/14637979/>`_.
-
-Once the script is available in your PATH, you can run ``bst-here`` to open a
-shell session inside a new container based off the latest version of the
-buildstream-fedora Docker image. The current working directory will be mounted
-inside the container at ``/src``.
-
-You can also run individual BuildStream commands as ``bst-here COMMAND``. For
-example: ``bst-here show systems/my-system.bst``. Note that BuildStream won't
-be able to integrate with Bash tab-completion if you invoke it in this way.
-
-Two Docker volumes are set up by the ``bst-here`` script:
-
- * ``buildstream-cache --`` mounted at ``~/.cache/buildstream``
- * ``buildstream-config --`` mounted at ``~/.config/``
-
-These are necessary so that your BuildStream cache and configuration files
-persist between invocations of ``bst-here``.
diff --git a/doc/source/install_linux_distro.rst b/doc/source/install_linux_distro.rst
deleted file mode 100644
index a547d4e..0000000
--- a/doc/source/install_linux_distro.rst
+++ /dev/null
@@ -1,30 +0,0 @@
-
-
-.. _install_linux_distro:
-
-Installing from distro packages
-===============================
-BuildStream is available on some linux distributions, here are
-some install instructions for the linux distributions which
-have packaged BuildStream.
-
-
-Arch Linux
-----------
-Packages for Arch exist in `AUR <https://wiki.archlinux.org/index.php/Arch_User_Repository#Installing_packages>`_.
-Two different package versions are available:
-
-* Latest release: `buildstream <https://aur.archlinux.org/packages/buildstream>`_
-* Latest development snapshot: `buildstream-git <https://aur.archlinux.org/packages/buildstream-git>`_
-
-
-Fedora
-------
-BuildStream is not yet in the official Fedora repositories, but you can
-install it from a Copr::
-
- sudo dnf copr enable bochecha/buildstream
- sudo dnf install buildstream
-
-Optionally, install the ``buildstream-docs`` package to have the BuildStream
-documentation in Devhelp or GNOME Builder.
diff --git a/doc/source/install_source.rst b/doc/source/install_source.rst
deleted file mode 100644
index bcd0898..0000000
--- a/doc/source/install_source.rst
+++ /dev/null
@@ -1,289 +0,0 @@
-
-
-Installing from source
-======================
-Until BuildStream is available in :ref:`your distro <install_linux_distro>`, you will
-need to install it yourself from source.
-
-
-Installing dependencies
------------------------
-Before installing BuildStream from source, it is necessary to first install
-the system dependencies. Below are some linux distribution specific instructions
-for installing these dependencies.
-
-BuildStream requires the following base system requirements:
-
-* python3 >= 3.5
-* bubblewrap >= 0.1.2
-* fuse2
-
-BuildStream also depends on the host tools for the :mod:`Source <buildstream.source>` plugins.
-Refer to the respective :ref:`source plugin <plugins_sources>` documentation for host tool
-requirements of specific plugins.
-
-The default plugins with extra host dependencies are:
-
-* bzr
-* deb
-* git
-* ostree
-* patch
-* pip
-* tar
-
-If you intend to push built artifacts to a remote artifact server,
-which requires special permissions, you will also need:
-
-* ssh
-
-
-Arch Linux
-~~~~~~~~~~
-Install the dependencies with::
-
- sudo pacman -S \
- python fuse2 bubblewrap \
- python-pip
-
-For the default plugins::
-
- sudo pacman -S \
- bzr git lzip ostree patch python-gobject
-
-
-The package *python-arpy* is required by the deb source plugin. This is not
-obtainable via `pacman`, you must get *python-arpy* from AUR:
-https://aur.archlinux.org/packages/python-arpy/
-
-To install::
-
- wget https://aur.archlinux.org/cgit/aur.git/snapshot/python-arpy.tar.gz
- tar -xvf python-arpy.tar.gz
- cd python-arpy
- makepkg -si
-
-
-Debian
-~~~~~~
-Install the dependencies with::
-
- sudo apt-get install \
- python3 fuse bubblewrap \
- python3-pip python3-dev
-
-For the default plugins:
-
-
-Stretch
-+++++++
-With stretch, you first need to ensure that you have the backports repository
-setup as described `here <https://backports.debian.org/Instructions/>`_
-
-By adding the following line to your sources.list::
-
- deb http://deb.debian.org/debian stretch-backports main
-
-And then running::
-
- sudo apt update
-
-At this point you should be able to get the system requirements for the default plugins with::
-
- sudo apt install \
- bzr git lzip patch python3-arpy python3-gi
- sudo apt install -t stretch-backports \
- gir1.2-ostree-1.0 ostree
-
-
-Buster or Sid
-+++++++++++++
-For debian unstable or testing, only the following line should be enough
-to get the system requirements for the default plugins installed::
-
- sudo apt-get install \
- lzip gir1.2-ostree-1.0 git bzr ostree patch python3-arpy python3-gi
-
-
-Fedora
-~~~~~~
-For recent fedora systems, the following line should get you the system
-requirements you need::
-
- dnf install -y \
- python3 fuse bubblewrap \
- python3-pip python3-devel
-
-For the default plugins::
-
- dnf install -y \
- bzr git lzip patch ostree python3-gobject
- pip3 install --user arpy
-
-
-Ubuntu
-~~~~~~
-
-
-Ubuntu 18.04 LTS or later
-+++++++++++++++++++++++++
-Install the dependencies with::
-
- sudo apt install \
- python3 fuse bubblewrap \
- python3-pip python3-dev
-
-For the default plugins::
-
- sudo apt install \
- bzr gir1.2-ostree-1.0 git lzip ostree patch python3-arpy python3-gi
-
-
-Ubuntu 16.04 LTS
-++++++++++++++++
-On Ubuntu 16.04, neither `bubblewrap <https://github.com/projectatomic/bubblewrap/>`_
-or `ostree <https://github.com/ostreedev/ostree>`_ are available in the official repositories.
-You will need to install them in whichever way you see fit. Refer the the upstream documentation
-for advice on this.
-
-
-Installing
-----------
-Once you have the base system dependencies, you can install the BuildStream
-python package as a regular user.
-
-
-Installing from PyPI (recommended)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Since we only ever publish :ref:`release versions <install_semantic_versioning>` on
-PyPI, it is currently recommended to use this installation path. This will
-ensure that you always have the latest recommended version of BuildStream that
-we recommend.
-
-To install from PyPI, you will additionally require:
-
-* pip for python3 (only required for setup)
-* Python 3 development libraries and headers
-
-Simply run the following command::
-
- pip3 install --user BuildStream
-
-This will install latest stable version of BuildStream and its pure python
-dependencies into your user's homedir in ``~/.local``.
-
-Keep following the instructions below to ensure that the ``bst``
-command is in your ``PATH`` and to enable bash completions for it.
-
-.. note::
-
- If you want a specific version of BuildStream, you can install it using
- ``pip install --user BuildStream==<version-number>``
-
-
-Upgrading from PyPI
-+++++++++++++++++++
-Once you have already installed BuildStream from PyPI, you can later update
-to the latest recommended version like so::
-
- pip install --user --upgrade BuildStream
-
-
-.. _install_git_checkout:
-
-Installing from a git checkout
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-To install directly from the `git repository <https://gitlab.com/BuildStream/buildstream.git>`_
-using python's ``pip`` package manager, you will additionally require:
-
-* pip for python3 (only required for setup)
-* Python 3 development libraries and headers
-* git (to checkout BuildStream)
-
-Before installing, please check the existing tags in the git repository
-and determine which version you want to install, and whether you want
-to install an official release version (recommended), or a development snapshot
-to help us out testing the bleeding edge of development. Follow the
-:ref:`semantic versioning guide <install_semantic_versioning>` to determine
-which tag you intend to install.
-
-Run the following commands::
-
- git clone https://gitlab.com/BuildStream/buildstream.git
- cd buildstream
- git checkout <desired release tag>
- pip3 install --user -e .
-
-This will install buildstream's pure python dependencies into
-your user's homedir in ``~/.local`` and will run BuildStream directly
-from the git checkout directory.
-
-Keep following the instructions below to ensure that the ``bst``
-command is in your ``PATH`` and to enable bash completions for it.
-
-.. note::
-
- We recommend the ``-e`` option because you can upgrade your
- installation by simply updating the checked out git repository.
-
- If you want a full installation that is not linked to your
- git checkout, just omit the ``-e`` option from the above commands.
-
-
-Upgrading from a git checkout
-+++++++++++++++++++++++++++++
-If you installed BuildStream from a local git checkout using ``-e`` option, all
-you need to do to upgrade BuildStream is to update your local git checkout::
-
- cd /path/to/buildstream
- git pull --rebase
-
-If you did not specify the ``-e`` option at install time or the dependancies
-have changed, you will need to cleanly reinstall BuildStream::
-
- pip3 uninstall buildstream
- cd /path/to/buildstream
- git pull --rebase
- pip3 install --user .
-
-.. note::
-
- If BuildStream has added any dependencies since the last upgrade,
- you will need to uninstall and reinstall to ensure those dependencies
- are met, regardless of whether you have used the ``-e`` option at
- install time.
-
-
-Post install setup
-------------------
-After having installed from source using any of the above methods, some
-setup will be required to use BuildStream.
-
-
-Adjust PATH
-~~~~~~~~~~~
-Since BuildStream is now installed under your local user's install directories,
-you need to ensure that ``PATH`` is adjusted.
-
-A regular way to do this is to add the following line to the end of your ``~/.bashrc``::
-
- export PATH="${PATH}:${HOME}/.local/bin"
-
-.. note::
-
- You will have to restart your terminal in order for these changes to take effect.
-
-
-Bash completions
-~~~~~~~~~~~~~~~~
-Bash completions are supported by sourcing the ``buildstream/data/bst``
-script found in the BuildStream repository. On many systems this script
-can be installed into a completions directory but when installing BuildStream
-without a package manager this is not an option.
-
-To enable completions for an installation of BuildStream you
-installed yourself from git, just append the script verbatim
-to your ``~/.bash_completion``:
-
-.. literalinclude:: ../../buildstream/data/bst
- :language: yaml
diff --git a/doc/source/install_versions.rst b/doc/source/install_versions.rst
deleted file mode 100644
index db0e35d..0000000
--- a/doc/source/install_versions.rst
+++ /dev/null
@@ -1,24 +0,0 @@
-
-
-.. _install_semantic_versioning:
-
-Semantic Versioning
-===================
-BuildStream follows the Semantic Versioning Convention `(SemVer) <https://semver.org/>`_,
-and uses even minor point numbers to denote releases intended for users while
-odd minor point numbers represent development snapshops.
-
-For example, for a given version number ``X.Y.Z``
- * The ``X.<even number>.*`` versions are releases intended for users.
- * The ``X.<odd number>.*`` versions are development spanshots intended for testing.
-
-If you are :ref:`installing from git <install_git_checkout>`, please look for the latest
-tag to ensure you're getting the latest release.
-
-* Latest release:
-
- .. include:: release-badge.rst
-
-* Latest development snapshot:
-
- .. include:: snapshot-badge.rst
diff --git a/doc/source/main_install.rst b/doc/source/main_install.rst
deleted file mode 100644
index 8890fb2..0000000
--- a/doc/source/main_install.rst
+++ /dev/null
@@ -1,29 +0,0 @@
-
-
-.. _install:
-
-Install
-=======
-
-.. include:: release-badge.rst
-
-.. include:: snapshot-badge.rst
-
-This section provides instructions for installing BuildStream and its
-companion artifact server on various platforms, along with any installation
-related materials.
-
-.. note::
-
- BuildStream is currently only supported natively on Linux. Users of Unix-like
- systems where Docker is available can still use BuildStream by following the
- :ref:`Docker install guide <docker>`
-
-.. toctree::
- :maxdepth: 1
-
- install_source
- install_linux_distro
- install_docker
- install_artifacts
- install_versions
diff --git a/doc/source/main_using.rst b/doc/source/main_using.rst
index 65786e9..5f71ebd 100644
--- a/doc/source/main_using.rst
+++ b/doc/source/main_using.rst
@@ -15,3 +15,4 @@ guides and information on user preferences and configuration.
using_examples
using_config
using_commands
+ using_configuring_artifact_server
diff --git a/doc/source/release-badge.rst b/doc/source/release-badge.rst
deleted file mode 100644
index 3a09b7f..0000000
--- a/doc/source/release-badge.rst
+++ /dev/null
@@ -1,26 +0,0 @@
-
-.. Use this file to include the badge in the documentation, but not in
- the README.rst or gitlab rendered materials, that doesnt work.
-
- This is partly a workaround for a sphinx issue, we will be able
- to avoid the raw html once this is implemented in sphinx:
-
- https://github.com/sphinx-doc/sphinx/issues/2240
-
- Using the <object> tag instead of the <img> tag which sphinx generates
- allows the svg to be "interactive", for us this basically means that
- the link we encode in the badge svg is used, rather than static urls
- which need to be used around the <img> tag.
-
- WARNING: The custom CSS on the style tag will need to change if we
- change the theme, so that the <object> tag behaves similar
- to how the <img> tag is themed by the style sheets.
-
-.. raw:: html
-
- <a class="reference external image-reference">
- <object style="margin-bottom:24px;vertical-align:middle"
- data="https://buildstream.gitlab.io/buildstream/_static/release.svg"
- type="image/svg+xml"/>
- </object>
- </a>
diff --git a/doc/source/snapshot-badge.rst b/doc/source/snapshot-badge.rst
deleted file mode 100644
index b4a3fc9..0000000
--- a/doc/source/snapshot-badge.rst
+++ /dev/null
@@ -1,26 +0,0 @@
-
-.. Use this file to include the badge in the documentation, but not in
- the README.rst or gitlab rendered materials, that doesnt work.
-
- This is partly a workaround for a sphinx issue, we will be able
- to avoid the raw html once this is implemented in sphinx:
-
- https://github.com/sphinx-doc/sphinx/issues/2240
-
- Using the <object> tag instead of the <img> tag which sphinx generates
- allows the svg to be "interactive", for us this basically means that
- the link we encode in the badge svg is used, rather than static urls
- which need to be used around the <img> tag.
-
- WARNING: The custom CSS on the style tag will need to change if we
- change the theme, so that the <object> tag behaves similar
- to how the <img> tag is themed by the style sheets.
-
-.. raw:: html
-
- <a class="reference external image-reference">
- <object style="margin-bottom:24px;vertical-align:middle"
- data="https://buildstream.gitlab.io/buildstream/_static/snapshot.svg"
- type="image/svg+xml"/>
- </object>
- </a>
diff --git a/doc/source/install_artifacts.rst b/doc/source/using_configuring_artifact_server.rst
similarity index 98%
rename from doc/source/install_artifacts.rst
rename to doc/source/using_configuring_artifact_server.rst
index 6bea7f5..2c4e761 100644
--- a/doc/source/install_artifacts.rst
+++ b/doc/source/using_configuring_artifact_server.rst
@@ -2,8 +2,8 @@
.. _artifacts:
-Installing an artifact server
-=============================
+Configuring Artifact Server
+===========================
BuildStream caches the results of builds in a local artifact cache, and will
avoid building an element if there is a suitable build already present in the
local artifact cache.
@@ -72,7 +72,7 @@ Installing the server
~~~~~~~~~~~~~~~~~~~~~
You will also need to install BuildStream on the artifact server in order
to receive uploaded artifacts over ssh. Follow the instructions for installing
-BuildStream :ref:`here <install>`
+BuildStream `here <https://buildstream.build/install.html>`_.
When installing BuildStream on the artifact server, it must be installed
in a system wide location, with ``pip3 install .`` in the BuildStream
[buildstream] 01/02: doc: show an additional level on ToC
Posted by gi...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
github-bot pushed a commit to branch tiagogomes/docs-improvements
in repository https://gitbox.apache.org/repos/asf/buildstream.git
commit 3247d22bcf8f6c90bc9fa131912408b8bd2141fc
Author: Tiago Gomes <ti...@codethink.co.uk>
AuthorDate: Fri Sep 28 10:46:59 2018 +0100
doc: show an additional level on ToC
---
doc/source/index.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/doc/source/index.rst b/doc/source/index.rst
index bc6ecbe..c72489b 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -15,7 +15,7 @@ Later sections provide detailed information on BuildStream internals.
.. toctree::
- :maxdepth: 1
+ :maxdepth: 2
main_about
main_install