-
Notifications
You must be signed in to change notification settings - Fork 8
Building MassOS
This guide shows you how to use the scripts in this repo to compile MassOS from source.
This guide is aimed at developers (see below). Most users won't want to compile MassOS themselves. If you aren't a developer and want to install MassOS normally, look at Installing MassOS.
Please read all of these carefully before settling on the decision to compile MassOS:
- Building MassOS takes a very long time, and the speed will vary massively depending on your CPU. The fastest CPUs will take a few hours to compile MassOS, however the build could take several days on slower systems. While we cannot state the time every CPU will take, here is a sample of how long different tested CPUs took to compile MassOS (all are estimations):
- Intel Core i5-4300U (2.9 GHz, 4 threads): ~13 Hours
- Intel Core i5-1035G4 (3.7 GHz, 8 threads): ~7 Hours
- Intel Xeon E-2286G (4.9 GHz, 12 threads): ~4 Hours
- AMD Ryzen 9 7900X (5.6 GHz, 24 threads): ~2.5 Hours
- The minimum amount of RAM needed to compile MassOS is based on how many threads your CPU has. You must have twice as much RAM as CPU threads. For example, if you have a CPU with 16 threads, you must have at least 32GB of RAM. Run
nprocif you are unsure how many threads your CPU has, andfree -hif you are unsure how much RAM you have. Swap can be used as a RAM alternative, however the build process may be significantly slowed down if the machine has to swap, so it is not recommended. - The second and third parts of the build (Stage 2 and Stage 3) must be run with root access, due to the fact that they make use of a chroot environment with mounted virtual filesystems. No alternatives are currently supported.
- MassOS is bootstrapped and built from an existing GNU/Linux system. We strongly recommend building from an existing installation of MassOS itself to keep the system robust and ensure there will not be any influence from a non-MassOS distribution. Additionally, MassOS contains all the necessary dependencies included for bootstrapping in Stage 1, so no additional dependencies will have to be manually installed. While it should, theoretically, be possible to build from any modern distro, we require that all official release builds are built from MassOS.
- Please note that if you choose to build from a non-MassOS distribution, it must be a very recent and up-to-date distribution (for example, the latest interim/non-LTS release of Ubuntu). In any case, the system CANNOT, UNDER ANY CIRCUMSTANCE, be running a Linux kernel older than 5.10. This is because MassOS configures Glibc (the core C library) to only support 5.10 and newer versions. This means that the MassOS system, in its entirety, will NOT build from or run on older kernels. This requirement is not an issue for MassOS itself, as the very first version of MassOS released back in 2021 launched with Linux 5.13, so MassOS has never supported older kernels than 5.10 anyway.
ADDITIONAL NOTE: Your CPU may be limited by default in order save power. If you are using a distribution that makes use of power-profiles-daemon (MassOS included), it is strongly recommended that you ensure the power profile is set to performance. You can do this with the following command:
powerprofilesctl set performance
Now you've read the above notices and are fully aware of what you're getting yourself into, you can proceed with building MassOS.
In order to build MassOS, you will first need to clone the GitHub repository locally. To do so, run the following commands:
git clone --recursive https://github.com/MassOS-Linux/MassOS
cd MassOS
This will checkout the current development version of MassOS. Note that, since it is in development, the build is not guaranteed to successfully complete and may exit unsuccessfully. If this occurs, please open an issue to report the problem.
During the experimental phase of MassOS, it is not currently possible to build stable releases. But a build is made for most commits which are pushed to the development branch, so your build should succeed.
Before you can begin the compiling process of MassOS, you must first download the source tarballs of all the software which make up the MassOS system. Fortunately, this command will automatically download them all for you:
./retrieve-sources.sh
NOTE: Ensure everything downloaded successfully. If the final message says something along the lines of "Some downloads may have failed", then you MUST NOT continue until all the downloads were successful. You can re-run the retrieve-sources.sh script to retry the download of the missing files (it won't re-download anything already successfully downloaded). Sometimes a download fails because the server hosting the source tarball is down, or it used to provide the file but has now decided to stop providing it for some reason. In this case, you will need to edit the offending URL in the source-urls file to a mirror which also hosts the same file.
Optionally, you can verify the integrity of the downloaded sources by running the following command:
./verify-sources.sh
The first part of the build process involves using the host system to build a temporary bootstrap system, including a compiler, linker, C library, and shell. This has to be done on the host system since a compiler can only be compiled using an existing compiler. This is also the reason why building from MassOS as the host system is strongly encouraged, even though the bootstrap process should eliminate as much influence from the host system as possible. Build the bootstrap system by running the following command:
./stage1.sh
Now the temporary tools have successfully been built, you can proceed with building the full MassOS system. This must be run as root since it makes use of a chroot environment with mounted virtual filesystems. Also, be aware that this is the part which takes the longest:
sudo ./stage2.sh
If, for some reason, the build fails and exits unsuccessfully, all is not lost. The MassOS build system has a "resume" functionality for Stage 2 and Stage 3. To use it, you will first need to inspect the build output to determine which point your build failed at. Once you have determined this, you must edit the build-system.sh script at the location massos-rootfs/sources/build-system.sh (not the one at the top level of the MassOS source tree, unless you are fixing a failure caused by it). Once you've edited it, remove lines 26 up to where the failure occurred. You can automate this with the command sed -i 26,XXXd massos-rootfs/sources/build-system.sh, where XXX gets replaced with the line number you are removing up to. Then, attempt to resume the build by running the following command:
sudo ./stage2-resume-failed.sh CONFIRM_STAGE2_RESUME=YES
If all goes well, the build should then pick up from where it left off and continue until it finishes successfully. Note that, however, in some cases, the failure could be caused by a broken dependency chain earlier in the build system, and in this case, it may be more advisable to restart the entire build process from the beginning (after fixing the problem, of course), by removing the massos-rootfs directory.
Once the core system is built, you can compile a desktop environment and finish the build. You once again have to run this as root, replacing <desktop> with a desktop environment in the stage3 folder (see stage3/README for more details). Use nodesktop if you want a command-line only build
sudo ./stage3.sh <desktop>
For example, for Xfce:
sudo ./stage3.sh xfce
The same rule for resuming a failed build applies here as it did for Stage 2; the script is named stage3-resume-failed.sh.
When the MassOS system is completely build and finished, an output tarball labelled massos-<VERSION>-rootfs-x86_64-<DESKTOP>.tar.xz will be created. It is highly recommended that you change ownership of the final output tarball back to your user. You can do this with the following command:
sudo chown $(whoami):$(whoami) massos-*.tar.xz
To create a Live CD ISO image for the build, run the following command, replacing <rootfs-filename> with the full name of the rootfs tarball:
sudo ./create-livecd.sh <rootfs-filename>.tar.xz
This also needs to be run as root, and again is recommended to change ownership back to your own user after it has completed, with the following command:
sudo chown $(whoami):$(whoami) massos-*.iso