diff options
author | bst-marge-bot <marge-bot@buildstream.build> | 2020-08-04 09:06:04 +0000 |
---|---|---|
committer | bst-marge-bot <marge-bot@buildstream.build> | 2020-08-04 09:06:04 +0000 |
commit | 713736231f7f80c7c1a723e44f248684e7cdb6b2 (patch) | |
tree | 08df1c8ecaafa645fb5021c3c3e699b17dad5985 | |
parent | b4a5df28972eb7191d703f0ad14aa2b522f7d036 (diff) | |
parent | 99d59a33bf768ced82841f0a54f48d7803f8bf9f (diff) | |
download | buildstream-713736231f7f80c7c1a723e44f248684e7cdb6b2.tar.gz |
Merge branch 'dwinship/reintroduce-install-instructions-to-docs' into 'master'
Reintroduce install instructions to docs
See merge request BuildStream/buildstream!1999
-rw-r--r-- | doc/source/index.rst | 1 | ||||
-rw-r--r-- | doc/source/main_install.rst | 340 |
2 files changed, 341 insertions, 0 deletions
diff --git a/doc/source/index.rst b/doc/source/index.rst index 4d4e24ac2..68b13dab4 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -17,6 +17,7 @@ Later sections provide detailed information on BuildStream internals. :maxdepth: 1 main_about + main_install main_using main_core CONTRIBUTING diff --git a/doc/source/main_install.rst b/doc/source/main_install.rst new file mode 100644 index 000000000..3cc895f3f --- /dev/null +++ b/doc/source/main_install.rst @@ -0,0 +1,340 @@ +Installing +========== + +Until BuildStream is available in your distro, you may need to install +it yourself from source. The necessary steps are: + +* :ref:`Install dependencies<install-dependencies>` +* :ref:`Install BuildBox<install-buildbox>` +* :ref:`Install BuildStream<install-buildstream>` (from a git checkout, or from PyPi) +* :ref:`Update PATH<post-install>` + +Alternatively, BuildStream can be run in :ref:`a container<install-container>`. + + +.. _install-dependencies: + +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.6 +- bubblewrap >= 0.1.2 +- fuse2 +- pip +- :ref:`buildbox-casd<install-buildbox>` + +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 +- git +- patch +- pip +- tar + + +Arch Linux +~~~~~~~~~~ +Install the dependencies with:: + + + sudo pacman -S python fuse2 bubblewrap python-pip + + +For the default plugins:: + + + sudo pacman -S bzr git lzip patch + + +Debian +~~~~~~ +Install the dependencies with:: + + + sudo apt-get install \ + python3 fuse bubblewrap \ + python3-pip python3-dev + +For the default plugins: + + sudo apt-get install \ + lzip git bzr patch + + +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 + + +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 git lzip patch + +Ubuntu 16.04 LTS +++++++++++++++++ +On Ubuntu 16.04, `bubblewrap <https://github.com/projectatomic/bubblewrap/>`_ +is not 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. + + +.. _install-buildbox: + +Installing BuildBox +------------------- + +BuildStream master now depends on buildbox-casd to manage the local CAS cache +and communicate with CAS servers. buildbox-run is used for sandboxing. BuildBox +components are still in development and there are no stable releases yet. +Thus, they're not available yet in Linux distros and they have to be manually +installed. + +These components can be installed from binaries, or built from source. + +Install binaries +~~~~~~~~~~~~~~~~ +| Linux x86-64 users can download statically linked binaries: `buildbox-x86_64-linux.tar.xz <https://buildbox-casd-binaries.nyc3.cdn.digitaloceanspaces.com/buildbox-x86_64-linux-0.0.9-983edf11.tar.xz>`_ +| ``sha256sum 983edf113e945ab723a9ddfd4c00dd855db0175c81373dbc0ad809045e5801a3`` + +The tarball contains the binaries ``buildbox-casd``, ``buildbox-fuse``, +``buildbox-run-bubblewrap`` and the symlink ``buildbox-run``, which should be +extracted into a directory in ``PATH``, e.g., ``~/.local/bin``. + + +Build from source +~~~~~~~~~~~~~~~~~ + +Each of the 4 buildbox components can be installed separately from their +respective git repositiories, and each respository has individual install +instructions. Make sure that you're installing the correct version of +each component. + +| **Buildbox-common:** See the installation section in: +| https://gitlab.com/BuildGrid/buildbox/buildbox-common/-/blob/0.0.9/README.rst +| (Be sure to install from the 0.0.9 tag.) + +| **Buildbox-casd:** See the installation section in: +| https://gitlab.com/BuildGrid/buildbox/buildbox-casd/-/blob/0.0.9/README.rst \ +| (Be sure to install from the 0.0.9 tag.) + +| **Buildbox-fuse:** See +| https://gitlab.com/BuildGrid/buildbox/buildbox-fuse/-/blob/0.0.8/INSTALL.rst +| (Be sure to install from the 0.0.8 tag.) + +| **Buildbox-run-bublewrap:** See the installation section in: +| https://gitlab.com/BuildGrid/buildbox/buildbox-run-bubblewrap/-/blob/master/README.rst +| (Be sure to install from the 0.0.8 tag.) + +Finally, configure buildbox-run-bubblewrap as the default buildbox-run +implementation:: + + ln -sv buildbox-run-bubblewrap /usr/local/bin/buildbox-run + + +.. _install-buildstream: + +Installing BuildStream +---------------------- + +Installing from PyPI +~~~~~~~~~~~~~~~~~~~~ +Once you have the base system dependencies, you can install the BuildStream +python package as a regular user. + +To install from PyPI, you will additionally require: + + - pip for python3 (only required for setup) + - Python 3 development libraries and headers + + +For the latest dev snapshot of BuildStream 2, simply run the following command:: + + pip3 install --user --pre BuildStream + +This will install latest dev snapshot of BuildStream and its pure python +dependencies into your user's homedir in ``~/.local``. + +.. note:: + + At time of writing, BuildStream 2 is only available as dev snapshots; this + is why the ``--pre`` option is required. Running + ``pip3 install --user BuildStream`` (without the ``--pre`` option) + will install Buildsteam 1. + +You can also install a specific dev snapshot of Buildstream by specifying the +version. eg ``pip3 install --user BuildStream==1.93.2.dev0``. +Available versions can be found on the BuildStream history page `on PyPi +<https://pypi.org/project/BuildStream/#history>`_. +Note that some of the oldest versions are not available on PyPI. + +Keep following the :ref:`instructions below<post-install>` to ensure that the ``bst`` +command is in your ``PATH``. + +Upgrading from PyPI ++++++++++++++++++++ +Once you have already installed BuildStream from PyPI, you can later update +to the latest dev snapshot like so:: + + + pip3 install --user --upgrade --pre BuildStream + + + +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. + +Run the following commands:: + + + git clone https://gitlab.com/BuildStream/buildstream.git + cd buildstream + git checkout <desired release tag> + pip3 install --user . + +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. + + +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, you will +need to cleanly reinstall BuildStream:: + + pip3 uninstall buildstream + cd /path/to/buildstream + git pull --rebase + pip3 install --user . + +Installing in virtual environments +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +You can consider installing BuildStream in a +`Virtual Environment <https://docs.python.org/3/tutorial/venv.html>`_ if you want +to install multiple versions of BuildStream, or to isolate BuildStream and its +dependencies from other Python packages. + +Here is how to install BuildStream stable and development snapshot releases in +virtual environments of their own:: + + + # Install BuildStream stable in an environment called "venv-bst-stable" + # (At time of writing, this will be BuildStream 1) + python3 -m venv venv-bst-stable + venv-bst-stable/bin/pip install BuildStream + + # Install BuildStream latest development snapshot in an environment + # called "venv-bst-latest" + # (At time of writing, this will be Buildstream 2) + python3 -m venv venv-bst-latest + venv-bst-latest/bin/pip install --pre BuildStream + +To start using BuildStream from the desired environment, you will need to +activate it first. Activating it will automatically add ``bst`` to your ``PATH`` +and set up other necessary environment variables:: + + + # Use BuildStream stable from venv-bst-stable + source venv-bst-stable/bin/activate + bst --version + + # Use BuildStream latest from venv-bst-latest + source venv-bst-latest/bin/activate + bst --version + + # Once you are done, remember to deactivate the virtual environment + deactivate + +If you do not want to manage your virtual environments manually, you can +consider using `pipx <https://docs.python.org/3/tutorial/venv.html>`_. + + +.. _post-install: + +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. + + +.. _install-container: + +Buildstream Inside a Container +------------------------------- + +If your system cannot provide the base requirements, it is possible to run +BuildStream within a container. This gives you an easy way to get started +using BuildStream on any Unix-like platform where containers are available, +including macOS. + +For details, see the `Buildstream Docker documentation +<https://gitlab.com/BuildStream/buildstream-docker-images/-/blob/master/USING.md>`_ |