summaryrefslogtreecommitdiff
path: root/README.md
blob: 73d265f94d9ff8fcb85aef0d3b85f099bad2465d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
Baserock reference system definitions
=====================================

Baserock is a system for developing embedded and appliance Linux systems. For
more information, see <http://wiki.baserock.org>.

These are some example definitions for use with Baserock tooling. You can fork
this repo and develop your own systems directly within it, or use it as a
reference point when developing your own set of definitions.

The systems listed in the elements/systems/ directory are example systems
that build and run at some point. The only ones we can be sure
that still build in current master of definitions are the ones that
we keep building in our ci system; they are listed in `.gitlab-ci.yml`.

BuildStream conversions
-----------------------

It is possible to use BuildStream to build Baserock definitions. The
BuildStream build tool uses a different definitions format, so a conversion
needs to be done first.

Run the `convert` script from the root of the repository and you will be
rewarded with an autogenerated set of .bst files in the elements/ subdirectory
which should be buildable using BuildStream.

To run `convert`, you will need defs2bst and ybd. The following commands, run
from the root of the repository, should be enough to do a conversion:

    git clone https://gitlab.com/BuildStream/defs2bst/
    git clone https://gitlab.com/baserock/ybd/
    ./convert

You can then build e.g. a devel-system using BuildStream:

    bst build systems/devel-system-content.bst

Some things are not supported by the BuildStream conversion tool, and will need
to be manually dealt with.

  * the build-essential stratum isn't automatically converted, the
    elements/gnu-toolchain.bst element is its equivalent and needs to be
    manually kept in sync with any changes

  * .configure and .write extensions need to be rewritten as BuildStream
    elements

  * non-x86_64 systems aren't automatically converted; BuildStream supports
    "arch conditionals" which should make it easier for a single tree of .bst
    files to support many platforms, but it's not easy to automatically achieve
    this in places like linux.bst where Baserock currently has many different
    equivalents

Bootstrap sysroots
------------------

BuildStream requires an initial set of sysroot binaries to "seed" its build
sandbox. We produce suitable binaries using the `bootstrap/stage3-sysroot.bst`
element, and host them at <https://ostree.baserock.org/releases>. These are
then pulled by the `gnu-toolchain/base.bst` element.

I expect that the sysroot binaries will rarely need to change as they are only
used to bootstrap the `gnu-toolchain.bst` stack, and that stack is then used to
build everything else. However there will occasionally need to be updates; the
process is documented below.

There are also detailed instructions on how to produce binaries for new platforms
at: http://wiki.baserock.org/guides/how-to-cross-bootstrap/

The release process needs to be done for each supported architecture. To get an
idea of what we consider supported, look in `gnu-toolchain/base.bst`. Where you
see `$arch` in these instructions, substitute the corresponding Baserock
architecture name for the current platform.

  1. Build and checkout the sysroot binaries:

        bst build bootstrap/stage3-sysroot.bst
        bst checkout bootstrap/stage3-sysroot.bst ./sysroot

  2. Add the provenance metadata:

        scripts/baserock-release-metadata > ./sysroot/metadata

  4. Clone the releases OSTree repo locally.

        ostree init --repo=releases --mode=archive-z2
        ostree remote add --repo=releases \
            origin https://ostree.baserock.org/releases/ --no-gpg-verify
        ostree pull --repo=releases origin stage3-sysroot/$arch

  5. Commit the binaries to the correct branch. 

      cd sysroot
      ostree commit --repo=../releases \
                    --branch=stage3-sysroot/$arch \
                    ./
      cd -

  6. Push to the releases repo. You will need an SSH key that is authorized to
     connect as ostree-releases@baserock.org -- contact admin@baserock.org if
     you need access. You will also need to have installed our version of
     [ostree-push](https://github.com/dbnicholson/ostree-push).

     ostree-push --repo=./releases \
        ssh://ostree-releases@ostree.baserock.org:22200/ stage3-sysroot/$arch

Once this is done you can update `base.bst` to pull in the new version of the
binaries (the `bst track` command can help with this). Note that the new version
won't be noticed by `bst track` until the summary file on ostree.baserock.org has
been updated, which may take up to a minute.

In future we should would GPG sign the release binaries, and we would automate
the whole process in GitLab CI.