sigh and remove the minus, convention is underscores, sigh
authorLuke Kenneth Casson Leighton <lkcl@lkcl.net>
Wed, 23 Aug 2023 15:30:59 +0000 (16:30 +0100)
committerLuke Kenneth Casson Leighton <lkcl@lkcl.net>
Wed, 23 Aug 2023 15:30:59 +0000 (16:30 +0100)
SFFS/debian-bootstrap.mdwn [deleted file]
SFFS/debian_bootstrap.mdwn [new file with mode: 0644]

diff --git a/SFFS/debian-bootstrap.mdwn b/SFFS/debian-bootstrap.mdwn
deleted file mode 100644 (file)
index c57b243..0000000
+++ /dev/null
@@ -1,93 +0,0 @@
-# Tutorial for bootstrapping Debian Bookworm (12) from source. 
-
-Useful Links (External):
-
-* [Read about sbuild and understand how it works](https://wiki.debian.org/sbuild)
-* [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)
-* [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)
-* [debootstrap wiki page](https://wiki.debian.org/Debootstrap) (optional, in case you want to customize your chroot)
-
-Useful links (Libre-SOC):
-
-* Devscripts Libre-SOC page: [[devscripts]]
-* [Libre-SOC devscripts repo](https://git.libre-soc.org/?p=dev-env-setup.git;a=tree)
-
-## Video Tutorial
-
-[todo](todo) 
-
-## Reasoning:
-
-Libre-SOC builds upon the OpenPOWER ISA v3.0 but does not include many parts of the architecture typically found on production silicon, like AltiVec, VSX, and 128-bit hardware floating point. Because of this, we need (at this time, might change in the future when glibc supports detecting VSX vs SVP64 etc) to rebuild the full software repository to not include any of those instructions, making it compliant with [sffs (slides 5 & 6)](https://ics2020.bsc.es/sites/default/files/uploaded/brian_thompto_ICS2020_SLIDES.pdf).
-
-You can approach this in two ways: either build the full base Debian chroot packages yourself using Debian's build tools, optionally automated with our [scripts](https://git.libre-soc.org/?p=dev-env-setup.git;a=tree), or use the [prebuilt rootfs] in a compressed tar archive.
-
-## System requirements
-
-- A POWER system that can run Debian Bookworm (meaning POWER8 and newer)
-- At least 80GB of hard disk space
-
-Cross compiling will make this process much more complicated and is generally not recommended.
-
-## Development Setup Scripts
-
-If you haven't already, clone Libre-SOC's development environment setup scripts.
-These are bash scripts, and greatly simplify the time it takes to create a:
-
-- Stable environment
-- With all software and libraries at specific versions
-(which are known to work).
-
-These attributes are absolutely critical, and no support will be
-provided, unless you use these scripts to setup a development environment. This
-helps us fix any bugs in the scripts, and make sure everyone runs on the same
-page.
-
-    $ git clone https://git.libre-soc.org/git/dev-env-setup.git
-
-Do *look through* the
-[code](https://git.libre-soc.org/?p=dev-env-setup.git;a=tree) before running
-any of those scripts.
-This is your own legal responsibility (to not run
-arbitrary code off of the internet) and we take no responsibility or accept
-any liability whatsoever for your use or misuse of them.
-
-It is expected for you to use Debian for the host OS (anything else is unsupported: many contributors have repeatedly gotten into trouble by not following this advice), while all the chroots - which are developed very specifically for "reproducible builds" - run Debian 10 (Buster).
-
-## Setting up the build schroot
-
-Scripts we will be using for the setup are:
-
-* `install-sbuild-apt-reqs` for installing sbuild and configuring it to Debian's defaults
-* `mk-schroot-bookworm` for creating the bookworm schroot used by sbuild and adding our dpkg-buildflags to build for sffs
-* `build-bookworm-sffs` to build the packages needed for a debootstrap chroot directory
-* `create-deb-repo` to create a local dpkg repository of the built packages
-* `mk-sffs-chroot` to finally create the chroot using the repository of built packages
-
-Commands to run in terminal to rebuild Debian 12 with sffs compliance:
-
-    $ cd dev-env-setup
-    $ sudo bash
-    # ./install-sbuild-apt-reqs
-    # ./mk-schroot-bookworm
-    # exit
-    $ ./build-bookworm-sffs
-    $ ./create-deb-repo
-    $ ./mk-sffs-chroot
-
-## Using prebuilt tarball
-
-If you prefer to use the prebuilt tarball (which will save days of your time), you could simply download and extract the tarball to a convenient location and chroot into it.
-
-    $ curl -O [link to be added]
-    $ mkdir bookworm-sffs && cd bookworm-sffs
-    $ tar xpvf bookworm-sffs.tar.xz --xattrs-include='*.*' --numeric-owner
-    $ cd ..
-    $ sudo chroot bookworm-sffs
-
-## Notes and issues
-
-* Some packages will refuse to build with sffs compliant build flags and need workarounds, this will be handled in the future.
-* The Linux kernel cannot boot without AltiVec and VSX, even though they are build-time options. The solution for now is to use [microwatt's 5.7 kernel](https://lore.kernel.org/all/CAPweEDw710zFK8KLZY5gsQxEkQKrDiFkNRgABY9HJZ1rxpeVCg@mail.gmail.com/T/) and to incorporate the needed patches upstream in the future.
-* Previous note also means this is purely a chroot environment, this page will be updated once it becomes possible to boot a full VM of this build.
-* glibc *may* have some issues on sffs, the only way to test this is to run on microwatt  which will be done soon.
diff --git a/SFFS/debian_bootstrap.mdwn b/SFFS/debian_bootstrap.mdwn
new file mode 100644 (file)
index 0000000..c57b243
--- /dev/null
@@ -0,0 +1,93 @@
+# Tutorial for bootstrapping Debian Bookworm (12) from source. 
+
+Useful Links (External):
+
+* [Read about sbuild and understand how it works](https://wiki.debian.org/sbuild)
+* [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)
+* [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)
+* [debootstrap wiki page](https://wiki.debian.org/Debootstrap) (optional, in case you want to customize your chroot)
+
+Useful links (Libre-SOC):
+
+* Devscripts Libre-SOC page: [[devscripts]]
+* [Libre-SOC devscripts repo](https://git.libre-soc.org/?p=dev-env-setup.git;a=tree)
+
+## Video Tutorial
+
+[todo](todo) 
+
+## Reasoning:
+
+Libre-SOC builds upon the OpenPOWER ISA v3.0 but does not include many parts of the architecture typically found on production silicon, like AltiVec, VSX, and 128-bit hardware floating point. Because of this, we need (at this time, might change in the future when glibc supports detecting VSX vs SVP64 etc) to rebuild the full software repository to not include any of those instructions, making it compliant with [sffs (slides 5 & 6)](https://ics2020.bsc.es/sites/default/files/uploaded/brian_thompto_ICS2020_SLIDES.pdf).
+
+You can approach this in two ways: either build the full base Debian chroot packages yourself using Debian's build tools, optionally automated with our [scripts](https://git.libre-soc.org/?p=dev-env-setup.git;a=tree), or use the [prebuilt rootfs] in a compressed tar archive.
+
+## System requirements
+
+- A POWER system that can run Debian Bookworm (meaning POWER8 and newer)
+- At least 80GB of hard disk space
+
+Cross compiling will make this process much more complicated and is generally not recommended.
+
+## Development Setup Scripts
+
+If you haven't already, clone Libre-SOC's development environment setup scripts.
+These are bash scripts, and greatly simplify the time it takes to create a:
+
+- Stable environment
+- With all software and libraries at specific versions
+(which are known to work).
+
+These attributes are absolutely critical, and no support will be
+provided, unless you use these scripts to setup a development environment. This
+helps us fix any bugs in the scripts, and make sure everyone runs on the same
+page.
+
+    $ git clone https://git.libre-soc.org/git/dev-env-setup.git
+
+Do *look through* the
+[code](https://git.libre-soc.org/?p=dev-env-setup.git;a=tree) before running
+any of those scripts.
+This is your own legal responsibility (to not run
+arbitrary code off of the internet) and we take no responsibility or accept
+any liability whatsoever for your use or misuse of them.
+
+It is expected for you to use Debian for the host OS (anything else is unsupported: many contributors have repeatedly gotten into trouble by not following this advice), while all the chroots - which are developed very specifically for "reproducible builds" - run Debian 10 (Buster).
+
+## Setting up the build schroot
+
+Scripts we will be using for the setup are:
+
+* `install-sbuild-apt-reqs` for installing sbuild and configuring it to Debian's defaults
+* `mk-schroot-bookworm` for creating the bookworm schroot used by sbuild and adding our dpkg-buildflags to build for sffs
+* `build-bookworm-sffs` to build the packages needed for a debootstrap chroot directory
+* `create-deb-repo` to create a local dpkg repository of the built packages
+* `mk-sffs-chroot` to finally create the chroot using the repository of built packages
+
+Commands to run in terminal to rebuild Debian 12 with sffs compliance:
+
+    $ cd dev-env-setup
+    $ sudo bash
+    # ./install-sbuild-apt-reqs
+    # ./mk-schroot-bookworm
+    # exit
+    $ ./build-bookworm-sffs
+    $ ./create-deb-repo
+    $ ./mk-sffs-chroot
+
+## Using prebuilt tarball
+
+If you prefer to use the prebuilt tarball (which will save days of your time), you could simply download and extract the tarball to a convenient location and chroot into it.
+
+    $ curl -O [link to be added]
+    $ mkdir bookworm-sffs && cd bookworm-sffs
+    $ tar xpvf bookworm-sffs.tar.xz --xattrs-include='*.*' --numeric-owner
+    $ cd ..
+    $ sudo chroot bookworm-sffs
+
+## Notes and issues
+
+* Some packages will refuse to build with sffs compliant build flags and need workarounds, this will be handled in the future.
+* The Linux kernel cannot boot without AltiVec and VSX, even though they are build-time options. The solution for now is to use [microwatt's 5.7 kernel](https://lore.kernel.org/all/CAPweEDw710zFK8KLZY5gsQxEkQKrDiFkNRgABY9HJZ1rxpeVCg@mail.gmail.com/T/) and to incorporate the needed patches upstream in the future.
+* Previous note also means this is purely a chroot environment, this page will be updated once it becomes possible to boot a full VM of this build.
+* glibc *may* have some issues on sffs, the only way to test this is to run on microwatt  which will be done soon.