[Notes] [Git][BuildStream/buildstream][juerg/remote-config] 6 commits: doc: updates considering website being live now



Title: GitLab

Jürg Billeter pushed to branch juerg/remote-config at BuildStream / buildstream

Commits:

15 changed files:

Changes:

  • CONTRIBUTING.rst
    ... ... @@ -1147,7 +1147,7 @@ To actually regenerate the code::
    1147 1147
     Documenting
    
    1148 1148
     -----------
    
    1149 1149
     BuildStream starts out as a documented project from day one and uses
    
    1150
    -sphinx to document itself.
    
    1150
    +`sphinx <www.sphinx-doc.org>`_ to document itself.
    
    1151 1151
     
    
    1152 1152
     This section discusses formatting policies for editing files in the
    
    1153 1153
     ``doc/source`` directory, and describes the details of how the docs are
    
    ... ... @@ -1194,10 +1194,8 @@ The BuildStream documentation style is as follows:
    1194 1194
         the target, e.g.: ``:ref:`Link text <anchor_name>```.
    
    1195 1195
         Note that the "_" prefix is not used when referring to the target.
    
    1196 1196
     
    
    1197
    -Useful links:
    
    1198
    -
    
    1199
    -For further information, please see the `Sphinx Documentation
    
    1200
    -<http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_.
    
    1197
    +For further information about using the reStructuredText with sphinx, please see the
    
    1198
    +`Sphinx Documentation <http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_.
    
    1201 1199
     
    
    1202 1200
     
    
    1203 1201
     Building Docs
    
    ... ... @@ -1266,10 +1264,101 @@ the ``man/`` subdirectory, which will be automatically included
    1266 1264
     in the buildstream distribution.
    
    1267 1265
     
    
    1268 1266
     
    
    1269
    -Documentation Examples
    
    1270
    -~~~~~~~~~~~~~~~~~~~~~~
    
    1271
    -The examples section of the documentation contains a series of standalone
    
    1272
    -examples, here are the criteria for an example addition.
    
    1267
    +User guide
    
    1268
    +~~~~~~~~~~
    
    1269
    +The :ref:`user guide <using>` is comprised of free form documentation
    
    1270
    +in manually written ``.rst`` files and is split up into a few sections,
    
    1271
    +of main interest are the :ref:`tutorial <tutorial>` and the
    
    1272
    +:ref:`examples <examples>`.
    
    1273
    +
    
    1274
    +The distinction of the two categories of user guides is important to
    
    1275
    +understand too.
    
    1276
    +
    
    1277
    +* **Tutorial**
    
    1278
    +
    
    1279
    +  The tutorial is structured as a series of exercises which start with
    
    1280
    +  the most basic concepts and build upon the previous chapters in order
    
    1281
    +  to arrive at a basic understanding of how to create BuildStream projects.
    
    1282
    +
    
    1283
    +  This series of examples should be easy enough to complete in a matter
    
    1284
    +  of a few hours for a new user, and should provide just enough insight to
    
    1285
    +  get the user started in creating their own projects.
    
    1286
    +
    
    1287
    +  Going through the tutorial step by step should also result in the user
    
    1288
    +  becoming proficient enough with the reference manual to get by on their own.
    
    1289
    +
    
    1290
    +* **Examples**
    
    1291
    +
    
    1292
    +  These exist to demonstrate how to accomplish more advanced tasks which
    
    1293
    +  are not always obvious and discoverable.
    
    1294
    +
    
    1295
    +  Alternatively, these also demonstrate elegant and recommended ways of
    
    1296
    +  accomplishing some tasks which could be done in various ways.
    
    1297
    +
    
    1298
    +
    
    1299
    +Guidelines
    
    1300
    +''''''''''
    
    1301
    +Here are some general guidelines for adding new free form documentation
    
    1302
    +to the user guide.
    
    1303
    +
    
    1304
    +* **Focus on a single subject**
    
    1305
    +
    
    1306
    +  It is important to stay focused on a single subject and avoid getting
    
    1307
    +  into tangential material when creating a new entry, so that the articles
    
    1308
    +  remain concise and the user is not distracted by unrelated subject material.
    
    1309
    +
    
    1310
    +  A single tutorial chapter or example should not introduce any additional
    
    1311
    +  subject material than the material being added for the given example.
    
    1312
    +
    
    1313
    +* **Reuse existing sample project elements**
    
    1314
    +
    
    1315
    +  To help avoid distracting from the topic at hand, it is always preferable to
    
    1316
    +  reuse the same project sample material from other examples and only deviate
    
    1317
    +  slightly to demonstrate the new material, than to create completely new projects.
    
    1318
    +
    
    1319
    +  This helps us remain focused on a single topic at a time, and reduces the amount
    
    1320
    +  of unrelated material the reader needs to learn in order to digest the new
    
    1321
    +  example.
    
    1322
    +
    
    1323
    +* **Don't be redundant**
    
    1324
    +
    
    1325
    +  When something has already been explained in the tutorial or in another example,
    
    1326
    +  it is best to simply refer to the other user guide entry in a new example.
    
    1327
    +
    
    1328
    +  Always prefer to link to the tutorial if an explanation exists in the tutorial,
    
    1329
    +  rather than linking to another example, where possible.
    
    1330
    +
    
    1331
    +* **Link into the reference manual at every opportunity**
    
    1332
    +
    
    1333
    +  The format and plugin API is 100% documented at all times. Whenever discussing
    
    1334
    +  anything about the format or plugin API, always do so while providing a link
    
    1335
    +  into the more terse reference material.
    
    1336
    +
    
    1337
    +  We don't want users to have to search for the material themselves, and we also
    
    1338
    +  want the user to become proficient at navigating the reference material over
    
    1339
    +  time.
    
    1340
    +
    
    1341
    +* **Use concise terminology**
    
    1342
    +
    
    1343
    +  As developers, we tend to come up with code names for features we develop, and
    
    1344
    +  then end up documenting a new feature in an example.
    
    1345
    +
    
    1346
    +  Never use a code name or shorthand to refer to a feature in the user guide, instead
    
    1347
    +  always use fully qualified sentences outlining very explicitly what we are doing
    
    1348
    +  in the example, or what the example is for in the case of a title.
    
    1349
    +
    
    1350
    +  We need to be considerate that the audience of our user guide is probably a
    
    1351
    +  proficient developer or integrator, but has no idea what we might have decided
    
    1352
    +  to name a given activity.
    
    1353
    +
    
    1354
    +
    
    1355
    +Structure of an example
    
    1356
    +'''''''''''''''''''''''
    
    1357
    +The :ref:`tutorial <tutorial>` and the :ref:`examples <examples>` sections
    
    1358
    +of the documentation contain a series of sample projects, each chapter in
    
    1359
    +the tutoral, or standalone example uses a sample project.
    
    1360
    +
    
    1361
    +Here is the the structure for adding new examples and tutorial chapters.
    
    1273 1362
     
    
    1274 1363
     * The example has a ``${name}``.
    
    1275 1364
     
    
    ... ... @@ -1280,11 +1369,17 @@ examples, here are the criteria for an example addition.
    1280 1369
     * The example has a documentation component.
    
    1281 1370
     
    
    1282 1371
       * This is added at ``doc/source/examples/${name}.rst``
    
    1283
    -  * A reference to ``examples/${name}`` is added to the toctree in ``doc/source/examples.rst``
    
    1372
    +  * An entry for ``examples/${name}`` is added to the toctree in ``doc/source/using_examples.rst``
    
    1284 1373
       * This documentation discusses the project elements declared in the project and may
    
    1285 1374
         provide some BuildStream command examples.
    
    1286 1375
       * This documentation links out to the reference manual at every opportunity.
    
    1287 1376
     
    
    1377
    +  .. note::
    
    1378
    +
    
    1379
    +     In the case of a tutorial chapter, the ``.rst`` file is added in at
    
    1380
    +     ``doc/source/tutorial/${name}.rst`` and an entry for ``tutorial/${name}``
    
    1381
    +     is added to ``doc/source/using_tutorial.rst``.
    
    1382
    +
    
    1288 1383
     * The example has a CI test component.
    
    1289 1384
     
    
    1290 1385
       * This is an integration test added at ``tests/examples/${name}``.
    

  • buildstream/_artifactcache/cascache.py
    ... ... @@ -365,7 +365,10 @@ class CASCache(ArtifactCache):
    365 365
             Raises: ArtifactError if no push remotes are configured.
    
    366 366
             """
    
    367 367
     
    
    368
    -        push_remotes = [r for r in self._remotes[project] if r.spec.push]
    
    368
    +        if self._has_push_remotes:
    
    369
    +            push_remotes = [r for r in self._remotes[project] if r.spec.push]
    
    370
    +        else:
    
    371
    +            push_remotes = []
    
    369 372
     
    
    370 373
             if not push_remotes:
    
    371 374
                 raise ArtifactError("CASCache: push_directory was called, but no remote artifact " +
    

  • doc/source/additional_docker.rst
    ... ... @@ -4,19 +4,18 @@
    4 4
     
    
    5 5
     BuildStream and Docker
    
    6 6
     ======================
    
    7
    -
    
    8 7
     BuildStream integrates with Docker in multiple ways. Here are some ways in
    
    9 8
     which these integrations work.
    
    10 9
     
    
    10
    +
    
    11 11
     Run BuildStream inside Docker
    
    12 12
     -----------------------------
    
    13
    +Refer to the `BuildStream inside Docker <https://buildstream.build/docker_install.html>`_
    
    14
    +documentation for instructions on how to run BuildStream as a Docker container.
    
    13 15
     
    
    14
    -Refer to the :ref:`BuildStream inside Docker <docker>` documentation for
    
    15
    -instructions on how to run BuildStream as a Docker container.
    
    16 16
     
    
    17 17
     Generate Docker images
    
    18 18
     ----------------------
    
    19
    -
    
    20 19
     The
    
    21 20
     `bst-docker-import script <https://gitlab.com/BuildStream/buildstream/blob/master/contrib/bst-docker-import>`_
    
    22 21
     can be used to generate a Docker image from built artifacts.
    

  • doc/source/index.rst
    ... ... @@ -13,20 +13,13 @@ They begin with a basic introduction to BuildStream, background
    13 13
     information on basic concepts, and a guide to the BuildStream command line interface.
    
    14 14
     Later sections provide detailed information on BuildStream internals.
    
    15 15
     
    
    16
    -
    
    17 16
     .. toctree::
    
    18 17
        :maxdepth: 1
    
    19 18
     
    
    20 19
        main_about
    
    21
    -   main_install
    
    22 20
        main_using
    
    23 21
        main_core
    
    24 22
        CONTRIBUTING
    
    25 23
     
    
    26
    -
    
    27
    -Resources
    
    28
    ----------
    
    29
    -* GitLab repository: https://gitlab.com/BuildStream/buildstream
    
    30
    -* Bug Tracking: https://gitlab.com/BuildStream/buildstream/issues
    
    31
    -* Mailing list: https://mail.gnome.org/mailman/listinfo/buildstream-list
    
    32
    -* IRC Channel: irc://irc.gnome.org/#buildstream
    24
    +For any other information, including `how to install BuildStream <https://buildstream.build/install.html>`_,
    
    25
    +refer to `the BuildStream website <https://buildstream.build>`_.

  • doc/source/install_docker.rst deleted
    1
    -
    
    2
    -
    
    3
    -.. _docker:
    
    4
    -
    
    5
    -BuildStream inside Docker
    
    6
    --------------------------
    
    7
    -If your system cannot provide the base system requirements for BuildStream, then it is possible to run buildstream within a Docker image.
    
    8
    -
    
    9
    -The BuildStream project provides
    
    10
    -`Docker images <https://hub.docker.com/r/buildstream/buildstream-fedora>`_
    
    11
    -containing BuildStream and its dependencies.
    
    12
    -This gives you an easy way to get started using BuildStream on any Unix-like
    
    13
    -platform where Docker is available, including Mac OS X.
    
    14
    -
    
    15
    -We recommend using the
    
    16
    -`bst-here wrapper script <https://gitlab.com/BuildStream/buildstream/blob/master/contrib/bst-here>`_
    
    17
    -which automates the necessary container setup. You can download it and make
    
    18
    -it executable like this:
    
    19
    -
    
    20
    -.. code:: bash
    
    21
    -
    
    22
    -  mkdir -p ~/.local/bin
    
    23
    -  curl --get https://gitlab.com/BuildStream/buildstream/raw/master/contrib/bst-here > ~/.local/bin/bst-here
    
    24
    -  chmod +x ~/.local/bin/bst-here
    
    25
    -
    
    26
    -Check if ``~/.local/bin`` appears in your PATH environment variable -- if it
    
    27
    -doesn't, you should
    
    28
    -`edit your ~/.profile so that it does <https://stackoverflow.com/questions/14637979/>`_.
    
    29
    -
    
    30
    -Once the script is available in your PATH, you can run ``bst-here`` to open a
    
    31
    -shell session inside a new container based off the latest version of the
    
    32
    -buildstream-fedora Docker image. The current working directory will be mounted
    
    33
    -inside the container at ``/src``.
    
    34
    -
    
    35
    -You can also run individual BuildStream commands as ``bst-here COMMAND``. For
    
    36
    -example: ``bst-here show systems/my-system.bst``. Note that BuildStream won't
    
    37
    -be able to integrate with Bash tab-completion if you invoke it in this way.
    
    38
    -
    
    39
    -Two Docker volumes are set up by the ``bst-here`` script:
    
    40
    -
    
    41
    - * ``buildstream-cache --`` mounted at ``~/.cache/buildstream``
    
    42
    - * ``buildstream-config --`` mounted at ``~/.config/``
    
    43
    -
    
    44
    -These are necessary so that your BuildStream cache and configuration files
    
    45
    -persist between invocations of ``bst-here``.

  • doc/source/install_linux_distro.rst deleted
    1
    -
    
    2
    -
    
    3
    -.. _install_linux_distro:
    
    4
    -
    
    5
    -Installing from distro packages
    
    6
    -===============================
    
    7
    -BuildStream is available on some linux distributions, here are
    
    8
    -some install instructions for the linux distributions which
    
    9
    -have packaged BuildStream.
    
    10
    -
    
    11
    -
    
    12
    -Arch Linux
    
    13
    -----------
    
    14
    -Packages for Arch exist in `AUR <https://wiki.archlinux.org/index.php/Arch_User_Repository#Installing_packages>`_.
    
    15
    -Two different package versions are available:
    
    16
    -
    
    17
    -* Latest release: `buildstream <https://aur.archlinux.org/packages/buildstream>`_
    
    18
    -* Latest development snapshot: `buildstream-git <https://aur.archlinux.org/packages/buildstream-git>`_
    
    19
    -
    
    20
    -
    
    21
    -Fedora
    
    22
    -------
    
    23
    -BuildStream is not yet in the official Fedora repositories, but you can
    
    24
    -install it from a Copr::
    
    25
    -
    
    26
    -  sudo dnf copr enable bochecha/buildstream
    
    27
    -  sudo dnf install buildstream
    
    28
    -
    
    29
    -Optionally, install the ``buildstream-docs`` package to have the BuildStream
    
    30
    -documentation in Devhelp or GNOME Builder.

  • doc/source/install_source.rst deleted
    1
    -
    
    2
    -
    
    3
    -Installing from source
    
    4
    -======================
    
    5
    -Until BuildStream is available in :ref:`your distro <install_linux_distro>`, you will
    
    6
    -need to install it yourself from source.
    
    7
    -
    
    8
    -
    
    9
    -Installing dependencies
    
    10
    ------------------------
    
    11
    -Before installing BuildStream from source, it is necessary to first install
    
    12
    -the system dependencies. Below are some linux distribution specific instructions
    
    13
    -for installing these dependencies.
    
    14
    -
    
    15
    -BuildStream requires the following base system requirements:
    
    16
    -
    
    17
    -* python3 >= 3.5
    
    18
    -* bubblewrap >= 0.1.2
    
    19
    -* fuse2
    
    20
    -
    
    21
    -BuildStream also depends on the host tools for the :mod:`Source <buildstream.source>` plugins.
    
    22
    -Refer to the respective :ref:`source plugin <plugins_sources>` documentation for host tool
    
    23
    -requirements of specific plugins.
    
    24
    -
    
    25
    -The default plugins with extra host dependencies are:
    
    26
    -
    
    27
    -* bzr
    
    28
    -* deb
    
    29
    -* git
    
    30
    -* ostree
    
    31
    -* patch
    
    32
    -* pip
    
    33
    -* tar
    
    34
    -
    
    35
    -If you intend to push built artifacts to a remote artifact server,
    
    36
    -which requires special permissions, you will also need:
    
    37
    -
    
    38
    -* ssh
    
    39
    -
    
    40
    -
    
    41
    -Arch Linux
    
    42
    -~~~~~~~~~~
    
    43
    -Install the dependencies with::
    
    44
    -
    
    45
    -  sudo pacman -S \
    
    46
    -      python fuse2 bubblewrap \
    
    47
    -      python-pip
    
    48
    -
    
    49
    -For the default plugins::
    
    50
    -
    
    51
    -  sudo pacman -S \
    
    52
    -      bzr git lzip ostree patch python-gobject
    
    53
    -
    
    54
    -
    
    55
    -The package *python-arpy* is required by the deb source plugin. This is not
    
    56
    -obtainable via `pacman`, you must get *python-arpy* from AUR:
    
    57
    -https://aur.archlinux.org/packages/python-arpy/
    
    58
    -
    
    59
    -To install::
    
    60
    -
    
    61
    -  wget https://aur.archlinux.org/cgit/aur.git/snapshot/python-arpy.tar.gz
    
    62
    -  tar -xvf python-arpy.tar.gz
    
    63
    -  cd python-arpy
    
    64
    -  makepkg -si
    
    65
    -
    
    66
    -
    
    67
    -Debian
    
    68
    -~~~~~~
    
    69
    -Install the dependencies with::
    
    70
    -
    
    71
    -  sudo apt-get install \
    
    72
    -      python3 fuse bubblewrap \
    
    73
    -      python3-pip python3-dev
    
    74
    -
    
    75
    -For the default plugins:
    
    76
    -
    
    77
    -
    
    78
    -Stretch
    
    79
    -+++++++
    
    80
    -With stretch, you first need to ensure that you have the backports repository
    
    81
    -setup as described `here <https://backports.debian.org/Instructions/>`_
    
    82
    -
    
    83
    -By adding the following line to your sources.list::
    
    84
    -
    
    85
    -  deb http://deb.debian.org/debian stretch-backports main
    
    86
    -
    
    87
    -And then running::
    
    88
    -
    
    89
    -  sudo apt update
    
    90
    -
    
    91
    -At this point you should be able to get the system requirements for the default plugins with::
    
    92
    -
    
    93
    -  sudo apt install \
    
    94
    -      bzr git lzip patch python3-arpy python3-gi
    
    95
    -  sudo apt install -t stretch-backports \
    
    96
    -      gir1.2-ostree-1.0 ostree
    
    97
    -
    
    98
    -
    
    99
    -Buster or Sid
    
    100
    -+++++++++++++
    
    101
    -For debian unstable or testing, only the following line should be enough
    
    102
    -to get the system requirements for the default plugins installed::
    
    103
    -
    
    104
    -  sudo apt-get install \
    
    105
    -      lzip gir1.2-ostree-1.0 git bzr ostree patch python3-arpy python3-gi
    
    106
    -
    
    107
    -
    
    108
    -Fedora
    
    109
    -~~~~~~
    
    110
    -For recent fedora systems, the following line should get you the system
    
    111
    -requirements you need::
    
    112
    -
    
    113
    -  dnf install -y \
    
    114
    -      python3 fuse bubblewrap \
    
    115
    -      python3-pip python3-devel
    
    116
    -
    
    117
    -For the default plugins::
    
    118
    -
    
    119
    -  dnf install -y \
    
    120
    -      bzr git lzip patch ostree python3-gobject
    
    121
    -  pip3 install --user arpy
    
    122
    -
    
    123
    -
    
    124
    -Ubuntu
    
    125
    -~~~~~~
    
    126
    -
    
    127
    -
    
    128
    -Ubuntu 18.04 LTS or later
    
    129
    -+++++++++++++++++++++++++
    
    130
    -Install the dependencies with::
    
    131
    -
    
    132
    -  sudo apt install \
    
    133
    -      python3 fuse bubblewrap \
    
    134
    -      python3-pip python3-dev
    
    135
    -
    
    136
    -For the default plugins::
    
    137
    -
    
    138
    -  sudo apt install \
    
    139
    -      bzr gir1.2-ostree-1.0 git lzip ostree patch python3-arpy python3-gi
    
    140
    -
    
    141
    -
    
    142
    -Ubuntu 16.04 LTS
    
    143
    -++++++++++++++++
    
    144
    -On Ubuntu 16.04, neither `bubblewrap <https://github.com/projectatomic/bubblewrap/>`_
    
    145
    -or `ostree <https://github.com/ostreedev/ostree>`_ are available in the official repositories.
    
    146
    -You will need to install them in whichever way you see fit. Refer the the upstream documentation
    
    147
    -for advice on this.
    
    148
    -
    
    149
    -
    
    150
    -Installing
    
    151
    -----------
    
    152
    -Once you have the base system dependencies, you can install the BuildStream
    
    153
    -python package as a regular user.
    
    154
    -
    
    155
    -
    
    156
    -Installing from PyPI (recommended)
    
    157
    -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    
    158
    -Since we only ever publish :ref:`release versions <install_semantic_versioning>` on
    
    159
    -PyPI, it is currently recommended to use this installation path. This will
    
    160
    -ensure that you always have the latest recommended version of BuildStream that
    
    161
    -we recommend.
    
    162
    -
    
    163
    -To install from PyPI, you will additionally require:
    
    164
    -
    
    165
    -* pip for python3 (only required for setup)
    
    166
    -* Python 3 development libraries and headers
    
    167
    -
    
    168
    -Simply run the following command::
    
    169
    -
    
    170
    -  pip3 install --user BuildStream
    
    171
    -
    
    172
    -This will install latest stable version of BuildStream and its pure python
    
    173
    -dependencies into your user's homedir in ``~/.local``.
    
    174
    -
    
    175
    -Keep following the instructions below to ensure that the ``bst``
    
    176
    -command is in your ``PATH`` and to enable bash completions for it.
    
    177
    -
    
    178
    -.. note::
    
    179
    -
    
    180
    -  If you want a specific version of BuildStream, you can install it using
    
    181
    -  ``pip install --user BuildStream==<version-number>``
    
    182
    -
    
    183
    -
    
    184
    -Upgrading from PyPI
    
    185
    -+++++++++++++++++++
    
    186
    -Once you have already installed BuildStream from PyPI, you can later update
    
    187
    -to the latest recommended version like so::
    
    188
    -
    
    189
    -  pip install --user --upgrade BuildStream
    
    190
    -
    
    191
    -
    
    192
    -.. _install_git_checkout:
    
    193
    -
    
    194
    -Installing from a git checkout
    
    195
    -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    
    196
    -To install directly from the `git repository <https://gitlab.com/BuildStream/buildstream.git>`_
    
    197
    -using python's ``pip`` package manager, you will additionally require:
    
    198
    -
    
    199
    -* pip for python3 (only required for setup)
    
    200
    -* Python 3 development libraries and headers
    
    201
    -* git (to checkout BuildStream)
    
    202
    -
    
    203
    -Before installing, please check the existing tags in the git repository
    
    204
    -and determine which version you want to install, and whether you want
    
    205
    -to install an official release version (recommended), or a development snapshot
    
    206
    -to help us out testing the bleeding edge of development. Follow the
    
    207
    -:ref:`semantic versioning guide <install_semantic_versioning>` to determine
    
    208
    -which tag you intend to install.
    
    209
    -
    
    210
    -Run the following commands::
    
    211
    -
    
    212
    -  git clone https://gitlab.com/BuildStream/buildstream.git
    
    213
    -  cd buildstream
    
    214
    -  git checkout <desired release tag>
    
    215
    -  pip3 install --user -e .
    
    216
    -
    
    217
    -This will install buildstream's pure python dependencies into
    
    218
    -your user's homedir in ``~/.local`` and will run BuildStream directly
    
    219
    -from the git checkout directory.
    
    220
    -
    
    221
    -Keep following the instructions below to ensure that the ``bst``
    
    222
    -command is in your ``PATH`` and to enable bash completions for it.
    
    223
    -
    
    224
    -.. note::
    
    225
    -
    
    226
    -   We recommend the ``-e`` option because you can upgrade your
    
    227
    -   installation by simply updating the checked out git repository.
    
    228
    -
    
    229
    -   If you want a full installation that is not linked to your
    
    230
    -   git checkout, just omit the ``-e`` option from the above commands.
    
    231
    -
    
    232
    -
    
    233
    -Upgrading from a git checkout
    
    234
    -+++++++++++++++++++++++++++++
    
    235
    -If you installed BuildStream from a local git checkout using ``-e`` option, all
    
    236
    -you need to do to upgrade BuildStream is to update your local git checkout::
    
    237
    -
    
    238
    -  cd /path/to/buildstream
    
    239
    -  git pull --rebase
    
    240
    -
    
    241
    -If you did not specify the ``-e`` option at install time or the dependancies
    
    242
    -have changed, you will need to cleanly reinstall BuildStream::
    
    243
    -
    
    244
    -  pip3 uninstall buildstream
    
    245
    -  cd /path/to/buildstream
    
    246
    -  git pull --rebase
    
    247
    -  pip3 install --user .
    
    248
    -
    
    249
    -.. note::
    
    250
    -
    
    251
    -   If BuildStream has added any dependencies since the last upgrade,
    
    252
    -   you will need to uninstall and reinstall to ensure those dependencies
    
    253
    -   are met, regardless of whether you have used the ``-e`` option at
    
    254
    -   install time.
    
    255
    -
    
    256
    -
    
    257
    -Post install setup
    
    258
    -------------------
    
    259
    -After having installed from source using any of the above methods, some
    
    260
    -setup will be required to use BuildStream.
    
    261
    -
    
    262
    -
    
    263
    -Adjust PATH
    
    264
    -~~~~~~~~~~~
    
    265
    -Since BuildStream is now installed under your local user's install directories,
    
    266
    -you need to ensure that ``PATH`` is adjusted.
    
    267
    -
    
    268
    -A regular way to do this is to add the following line to the end of your ``~/.bashrc``::
    
    269
    -
    
    270
    -  export PATH="${PATH}:${HOME}/.local/bin"
    
    271
    -
    
    272
    -.. note::
    
    273
    -
    
    274
    -   You will have to restart your terminal in order for these changes to take effect.
    
    275
    -
    
    276
    -
    
    277
    -Bash completions
    
    278
    -~~~~~~~~~~~~~~~~
    
    279
    -Bash completions are supported by sourcing the ``buildstream/data/bst``
    
    280
    -script found in the BuildStream repository. On many systems this script
    
    281
    -can be installed into a completions directory but when installing BuildStream
    
    282
    -without a package manager this is not an option.
    
    283
    -
    
    284
    -To enable completions for an installation of BuildStream you
    
    285
    -installed yourself from git, just append the script verbatim
    
    286
    -to your ``~/.bash_completion``:
    
    287
    -
    
    288
    -.. literalinclude:: ../../buildstream/data/bst
    
    289
    -   :language: yaml

  • doc/source/install_versions.rst deleted
    1
    -
    
    2
    -
    
    3
    -.. _install_semantic_versioning:
    
    4
    -
    
    5
    -Semantic Versioning
    
    6
    -===================
    
    7
    -BuildStream follows the Semantic Versioning Convention `(SemVer) <https://semver.org/>`_,
    
    8
    -and uses even minor point numbers to denote releases intended for users while
    
    9
    -odd minor point numbers represent development snapshops.
    
    10
    -
    
    11
    -For example, for a given version number ``X.Y.Z``
    
    12
    - * The ``X.<even number>.*`` versions are releases intended for users.
    
    13
    - * The ``X.<odd number>.*`` versions are development spanshots intended for testing.
    
    14
    -
    
    15
    -If you are :ref:`installing from git <install_git_checkout>`, please look for the latest
    
    16
    -tag to ensure you're getting the latest release.
    
    17
    -
    
    18
    -* Latest release:
    
    19
    -
    
    20
    -  .. include:: release-badge.rst
    
    21
    -
    
    22
    -* Latest development snapshot:
    
    23
    -
    
    24
    -  .. include:: snapshot-badge.rst

  • doc/source/main_install.rst deleted
    1
    -
    
    2
    -
    
    3
    -.. _install:
    
    4
    -
    
    5
    -Install
    
    6
    -=======
    
    7
    -
    
    8
    -.. include:: release-badge.rst
    
    9
    -
    
    10
    -.. include:: snapshot-badge.rst
    
    11
    -
    
    12
    -This section provides instructions for installing BuildStream and its
    
    13
    -companion artifact server on various platforms, along with any installation
    
    14
    -related materials.
    
    15
    -
    
    16
    -.. note::
    
    17
    -
    
    18
    -   BuildStream is currently only supported natively on Linux. Users of Unix-like
    
    19
    -   systems where Docker is available can still use BuildStream by following the
    
    20
    -   :ref:`Docker install guide <docker>`
    
    21
    -
    
    22
    -.. toctree::
    
    23
    -   :maxdepth: 1
    
    24
    -
    
    25
    -   install_source
    
    26
    -   install_linux_distro
    
    27
    -   install_docker
    
    28
    -   install_artifacts
    
    29
    -   install_versions

  • doc/source/main_using.rst
    1 1
     
    
    2 2
     
    
    3
    +.. _using:
    
    4
    +
    
    3 5
     Using
    
    4 6
     =====
    
    5 7
     This section includes user facing documentation including tutorials,
    
    ... ... @@ -15,3 +17,4 @@ guides and information on user preferences and configuration.
    15 17
        using_examples
    
    16 18
        using_config
    
    17 19
        using_commands
    
    20
    +   using_configuring_artifact_server

  • doc/source/release-badge.rst deleted
    1
    -
    
    2
    -.. Use this file to include the badge in the documentation, but not in
    
    3
    -   the README.rst or gitlab rendered materials, that doesnt work.
    
    4
    -
    
    5
    -   This is partly a workaround for a sphinx issue, we will be able
    
    6
    -   to avoid the raw html once this is implemented in sphinx:
    
    7
    -
    
    8
    -       https://github.com/sphinx-doc/sphinx/issues/2240
    
    9
    -
    
    10
    -   Using the <object> tag instead of the <img> tag which sphinx generates
    
    11
    -   allows the svg to be "interactive", for us this basically means that
    
    12
    -   the link we encode in the badge svg is used, rather than static urls
    
    13
    -   which need to be used around the <img> tag.
    
    14
    -
    
    15
    -   WARNING: The custom CSS on the style tag will need to change if we
    
    16
    -            change the theme, so that the <object> tag behaves similar
    
    17
    -	    to how the <img> tag is themed by the style sheets.
    
    18
    -
    
    19
    -.. raw:: html
    
    20
    -
    
    21
    -   <a class="reference external image-reference">
    
    22
    -     <object style="margin-bottom:24px;vertical-align:middle"
    
    23
    -             data=""
    
    24
    -	     type="image/svg+xml"/>
    
    25
    -     </object>
    
    26
    -   </a>

  • doc/source/snapshot-badge.rst deleted
    1
    -
    
    2
    -.. Use this file to include the badge in the documentation, but not in
    
    3
    -   the README.rst or gitlab rendered materials, that doesnt work.
    
    4
    -
    
    5
    -   This is partly a workaround for a sphinx issue, we will be able
    
    6
    -   to avoid the raw html once this is implemented in sphinx:
    
    7
    -
    
    8
    -       https://github.com/sphinx-doc/sphinx/issues/2240
    
    9
    -
    
    10
    -   Using the <object> tag instead of the <img> tag which sphinx generates
    
    11
    -   allows the svg to be "interactive", for us this basically means that
    
    12
    -   the link we encode in the badge svg is used, rather than static urls
    
    13
    -   which need to be used around the <img> tag.
    
    14
    -
    
    15
    -   WARNING: The custom CSS on the style tag will need to change if we
    
    16
    -            change the theme, so that the <object> tag behaves similar
    
    17
    -	    to how the <img> tag is themed by the style sheets.
    
    18
    -
    
    19
    -.. raw:: html
    
    20
    -
    
    21
    -   <a class="reference external image-reference">
    
    22
    -     <object style="margin-bottom:24px;vertical-align:middle"
    
    23
    -             data=""
    
    24
    -	     type="image/svg+xml"/>
    
    25
    -     </object>
    
    26
    -   </a>

  • doc/source/install_artifacts.rstdoc/source/using_configuring_artifact_server.rst
    ... ... @@ -2,8 +2,8 @@
    2 2
     
    
    3 3
     .. _artifacts:
    
    4 4
     
    
    5
    -Installing an artifact server
    
    6
    -=============================
    
    5
    +Configuring Artifact Server
    
    6
    +===========================
    
    7 7
     BuildStream caches the results of builds in a local artifact cache, and will
    
    8 8
     avoid building an element if there is a suitable build already present in the
    
    9 9
     local artifact cache.
    
    ... ... @@ -72,7 +72,7 @@ Installing the server
    72 72
     ~~~~~~~~~~~~~~~~~~~~~
    
    73 73
     You will also need to install BuildStream on the artifact server in order
    
    74 74
     to receive uploaded artifacts over ssh. Follow the instructions for installing
    
    75
    -BuildStream :ref:`here <install>`
    
    75
    +BuildStream `here <https://buildstream.build/install.html>`_.
    
    76 76
     
    
    77 77
     When installing BuildStream on the artifact server, it must be installed
    
    78 78
     in a system wide location, with ``pip3 install .`` in the BuildStream
    

  • doc/source/using_examples.rst
    1 1
     
    
    2
    +
    
    3
    +.. _examples:
    
    4
    +
    
    2 5
     Examples
    
    3 6
     ========
    
    4 7
     This page contains documentation for real examples of BuildStream projects,
    

  • doc/source/using_tutorial.rst
    1 1
     
    
    2
    +
    
    3
    +.. _tutorial:
    
    4
    +
    
    2 5
     Tutorial
    
    3 6
     ========
    
    4 7
     This is a step by step walkthrough meant help the user quickly get
    



  • [Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]