1 # Tutorial for bootstrapping Debian Bookworm (12) from source.
3 **This project is part of [NLnet NGI0 Entrust](https://nlnet.nl/entrust)
4 and has received funding from the European Union’s Horizon Europe research and innovation programme under grant agreement No 101069594.**
8 * [Read about sbuild and understand how it works](https://wiki.debian.org/sbuild)
9 * [dpkg-buildflags man page](https://manpages.debian.org/bookworm/dpkg-dev/dpkg-buildflags.1.en.html) (optional, in case some flags need to be changed)
10 * [apt-ftparchive man page](https://manpages.debian.org/bookworm/apt-utils/apt-ftparchive.1.en.html) (optional, in case you want to customize the repo)
11 * [debootstrap wiki page](https://wiki.debian.org/Debootstrap) (optional,
12 in case you want to customize your chroot)
13 * please note this tarball contains executable binaries and it is 100% your responsibility to check them or take appropriate measures. we take no responsibility and accept no liability <https://ftp.libre-soc.org/sffs/debian-12-sffs.2023sep01.tar.xz>. downloading this file constitutes your agreement to these terms.
15 Useful links (Libre-SOC):
17 * bugreport <https://bugs.libre-soc.org/show_bug.cgi?id=1130>
18 * Devscripts Libre-SOC page: [[HDL_workflow/devscripts]]
19 * [Libre-SOC devscripts repo](https://git.libre-soc.org/?p=dev-env-setup.git;a=tree)
27 Libre-SOC builds upon the OpenPOWER ISA v3.0 but does not include
28 many parts of the architecture typically found on production
29 silicon, like AltiVec, VSX, and 128-bit hardware floating
30 point. Because of this, we need (at this time, might change
31 in the future when glibc supports detecting VSX vs SVP64 etc)
32 to rebuild the full software repository to not include any of
33 those instructions, making it compliant with [sffs (slides 5 &
34 6)](https://ics2020.bsc.es/sites/default/files/uploaded/brian_thompto_ICS2020_SLIDES.pdf).
36 You can approach this in two ways: either build the full base Debian
37 chroot packages yourself using Debian's build tools, optionally automated
38 with our [scripts](https://git.libre-soc.org/?p=dev-env-setup.git;a=tree),
39 or use the [prebuilt rootfs for which you accept full liability and responsibility](https://ftp.libre-soc.org/sffs/debian-12-sffs.2023sep01.tar.xz) in a compressed tar archive.
41 ## System requirements
43 - A POWER system that can run Debian Bookworm (meaning POWER8 and newer)
44 - At least 80GB of hard disk space
46 Cross compiling will make this process much more complicated and is
47 generally not recommended.
49 ## Development Setup Scripts
51 If you haven't already, clone Libre-SOC's development environment setup
52 scripts. These are bash scripts, and greatly simplify the time it takes
56 - With all software and libraries at specific versions
57 (which are known to work).
59 These attributes are absolutely critical, and no support will be provided,
60 unless you use these scripts to setup a development environment. This
61 helps us fix any bugs in the scripts, and make sure everyone runs on
64 $ git clone https://git.libre-soc.org/git/dev-env-setup.git
67 [code](https://git.libre-soc.org/?p=dev-env-setup.git;a=tree) before running
69 This is your own legal responsibility (to not run
70 arbitrary code off of the internet) and we take no responsibility or accept
71 any liability whatsoever for your use or misuse of them.
73 It is expected for you to use Debian for the host OS (anything else is
74 unsupported: many contributors have repeatedly gotten into trouble by
75 not following this advice), while all the chroots - which are developed
76 very specifically for "reproducible builds" - run Debian 10 (Buster).
78 ## Setting up the build schroot
80 Scripts we will be using for the setup are:
82 * `install-sbuild-apt-reqs` for installing sbuild and configuring it to
84 * `mk-schroot-bookworm` for creating the bookworm schroot used by sbuild
85 and adding our dpkg-buildflags to build for sffs
86 * `build-glibc-debian` to build glibc, currently has to be standalone because of [this](https://bugs.libre-soc.org/show_bug.cgi?id=1130#c8)
87 * `add-sffs-flags-debian` to add the SFFS CFLAGS
88 * `build-bookworm-sffs` to build the packages needed for a debootstrap
90 * `create-deb-repo` to create a local dpkg repository of the built packages
91 * `mk-sffs-chroot` to finally create the chroot using the repository of
94 Commands to run in terminal to rebuild Debian 12 with sffs compliance:
98 # ./install-sbuild-apt-reqs
99 # ./mk-schroot-bookworm
101 $ ./build-glibc-debian
103 # ./add-sffs-flags-debian
105 $ ./build-bookworm-sffs
109 ## Using prebuilt tarball
111 If you prefer to use the prebuilt tarball (which will save days of your
112 time), you could simply download and extract the tarball to a convenient
113 location and chroot into it. Bear in mind though that it is entirely your
114 responsibility when downloading arbitrary binaries, and we accept no
115 liability whatsoever for anything arising by you downloading them.
117 $ curl -O https://ftp.libre-soc.org/sffs/debian-12-sffs.2023sep01.tar.xz
118 $ mkdir bookworm-sffs && cd bookworm-sffs
119 $ tar xpvf bookworm-sffs.tar.xz --xattrs-include='*.*' --numeric-owner
121 $ sudo chroot bookworm-sffs
123 # Testing for VSX in object files
125 To verify that our buildflags were applied by the build tools and
126 respected by the build scripts of packages, we need to check for the
127 inclusion of VSX as well as any other instructions not available in SFFS.
129 This is not a perfect solution and the proper way would be either to:
131 - Simulate an SFFS compliant chip running this code such as
132 [Microwatt](https://libre-soc.org/HDL_workflow/microwatt/)
133 (very time consuming)
134 - Use a softcore FPGA core or ASIC of Microwatt /
135 LibreSOC to run this code (doable, FPGA softcore
136 [in progress](https://bugs.libre-soc.org/show_bug.cgi?id=1037))
137 - Use the finalized Libre-SOC chip (doable once it is ready)
139 Also note that this only tests for a subset of VSX instructions at the
140 moment, more will be added in the future, this is simply a quick test to
141 run before attempting to run on simulation and/or a softcore as both can
142 be somewhat time consuming. In other words, if this test gives any VSX
143 instructions, don't attempt to run the code in simulation or a softcore
144 to avoid wasting precious time.
146 To attempt this test, you will need the scripts from our `dev-env-setup`
149 $ git clone https://git.libre-soc.org/git/dev-env-setup.git
151 Again, previous notes about running the scripts apply here, do make sure
152 to read whatever you run, they are short and human-readable.
154 Edit the `test-vsx` script to point the `CHROOT` variable to your
155 respective chroot of Debian, read through the script thoroughly, and run
159 If you see any number of instructions in certain binary files, those
160 files do contain VSX and work needs to be done (patching the build
161 scripts and/or source code) for these packages. If not, great! Try to
162 run this in a proper SFFS environment to fully test the code you have.
164 You can also test specific binaries at any time by running this part of
167 $ objdump -d $OBJ_FILE | fgrep -of VSX_INSNS.txt | sort | uniq -c \
168 | awk '{print $2 " " $1}'
170 Where `$OBJ_FILE` is the binary you need to check.
174 * Some packages will refuse to build with sffs compliant build flags
175 and need workarounds, this will be handled in the future.
176 * The Linux kernel cannot boot without AltiVec and VSX, even though they
177 are build-time options. The solution for now is to use [microwatt's 5.7
178 kernel](https://lore.kernel.org/all/CAPweEDw710zFK8KLZY5gsQxEkQKrDiFkNRgABY9HJZ1rxpeVCg@mail.gmail.com/T/)
179 and to incorporate the needed patches upstream in the future.
180 * Previous note also means this is purely a chroot environment, this page
181 will be updated once it becomes possible to boot a full VM of this build.
182 * glibc *may* have some issues on sffs, the only way to test this is to
183 run on microwatt which will be done soon.