--- /dev/null
+# Tutorial for bootstrapping Gentoo with sffs compliance from source.
+
+Useful Links (External):
+
+* [Read the Gentoo handbook thoroughly, it's all you need](https://wiki.gentoo.org/wiki/Handbook:PPC64)
+
+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 stage 3 system 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 Gentoo stage3 packages yourself using the [handbook](https://wiki.gentoo.org/wiki/Handbook:PPC64), 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.
+
+Do note that given the rolling release nature of Gentoo, it is almost impossible to get the same system with the specific package versions we have without using our tarball. If you still want to do a full rebuild but guarantee that the software versions stay the same, this guide will also explain how it can be done using our tarball.
+
+## 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. They may be confusing, however after reading a few you'll start to become more familiar with them.
+
+It is expected for you to use Debian, we mostly use 11 (Bullseye) for the host OS, while all the chroots run Debian 10 (Buster).
+
+## Setting up Gentoo from tarball (recommended method)
+
+You will need to run these commands:
+
+ $ curl -O [link to tarball]
+ # sudo bash
+ # mkdir gentoo-sffs && cd gentoo-sffs
+ # tar xpvf gentoo-sffs.tar.xz --xattrs-include='*.*' --numeric-owner
+ # cd ..
+ # chroot gentoo-sffs
+
+# (Optional) Rebuilding Gentoo from source without upgrading
+
+We conveniently keep the sources of all the packages on the system in the tarball as well, in case they become unavailable online at any point in time.
+
+ # chroot gentoo-sffs
+ # source /etc/profile
+ # emerge -e --ask --keep-going @world
+
+# (Optional) Building an updated Gentoo SFFS
+
+This is highly not recommended unless you specifically want to explore how newer versions of software will behave when built with the SFFS flags.
+
+One way of doing this is to just set up Gentoo SFFS from the provided tarball and then upgrade everything, that is much simpler and easier to roll-back if need be.
+
+After having a working chroot using our tarball as outlined earlier, run these commands in the chroot:
+
+ # emerge-webrsync
+ # emerge --ask --verbose --update --deep --newuse @world
+
+The other way is to create a new Gentoo chroot or virtual machine under POWER using the [handbook](https://wiki.gentoo.org/wiki/Handbook:PPC64), and once you reach the [stage3 tarball](https://wiki.gentoo.org/wiki/Handbook:PPC64/Installation/Stage#Unpacking_the_stage_tarball) step, download our [make.conf](link) and copy it to
+ `/etc/portage/make.conf`, replacing the provided one, and run:
+
+ # emerge -e --ask --keep-going @world
+ # emerge-webrsync
+ # emerge --ask --verbose --update --deep --newuse @world
+
+To first rebuild Gentoo for SFFS, and then update the repositories, and finally to upgrade the software you have.
+
+## Notes and issues
+
+* Gentoo's base system packages will not complain when building for SFFS (as of July 2023, can change depending on updates)
+* 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.
projects / libreriscv.git / commitdiff