- Physix Linux Project -
    MIT/GPLv2 License
===========================

Disclaimer:
============
The programs included with this project are free software; This Distribution
of GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent permitted by
applicable law.


Errata:
=======
The software used in Physix is constantly being updated. The best way to see fixes to
errors, warnings, and security exploits is to contribute a patch or communicate the need
for an update by opening a task on GitHub.


Definition:
===========
Physix is an Experimental, Automated, Build-From-Source, Linux Distribution
for i386, and x86_64. It is derived from the Linux From Scratch (LFS+BLFS)
technical books.


Who should use Physix?
======================
The target audience for this project are Linux Enthusiasts with medium
or higher level of expeirnece using *nix, and some experience in Python
and Bash programming. It is recommended that you have at least a general
understanding of the Linux From Scratch book.


Media:
======
* The Build Process Demo: https://youtu.be/57FnNBbi728


Quickstart A: Install to blank storage device.
===========
NOTE: This installation path is intended for installation on a blank storage device which is not
shareed with any other installed operating systems.

0. Install required tools on the host system:
	* Debian 10.2.0 : sudo apt-get install gcc g++ make gawk bison parted texinfo flex btrfs-tools vim git lvm2
	* Ubuntu 20.10  : sudo apt-get install gcc g++ make gawk bison parted texinfo flex btrfs-progs vim git lvm2   
	* Fedora 32     : sudo dnf install gcc g++ make gawk bison parted texinfo flex btrfs-tools vim git lvm2

1. git clone https://github.com/PhysixProject/physix.git
   cd physix

2. Edit physix.conf: Set your mandatory configs.
     CONF_SKIP_PARTITIONING=n
     CONF_UEFI_ENABLE=
     CONF_ROOT_DEVICE=
     CONF_UEFI_DEV_PART=
     CONF_BOOT_DEV_PART=
     CONF_INSTALL_DEV_PARTITION=
     CONF_ETH_INTERFACE=

   NOTE_1: The device you are installing to (CONF_ROOT_DEVICE) should be at least 60G AND blank.

   NOTE_2: Verify '/sbin' is in your environment PATH.
           echo $PATH | grep '\/sbin'

3. Set up the disk partitions by running:
	 ./catalyst -i physix.conf
   NOTE: This will move this git repository to /mnt/physix/opt/admin/physix

4. Run build script.
	 cd /mnt/physix/opt/admin/physix ; ./BUILD_BASE_SYSTEM.sh

5. Configure bootloader:
   Use your host system's grub.cfg as is, and add a Physix menu entry to it. A mock-up
   entry for this can be found at /boot/physix-grub.cfg.

6. Reboot.

7. After reboot, continue building the remaining recipes.
   # ./catalyst -p <recipe>
   # ./catalyst -b <recipe>


Quickstart B: Install to a Selected Partition.
===========
NOTE: This installation process is intended for installing Physix on a storage device which is
ALSO shared by another Operating system. The main difference between Quickstart A and B, is that 
partitioning is not performed; And grub.cfg will need to be setup manually. A mockup example is
written to /boot/physix-grub.cfg.

0. Install required tools on the host system:
    * Debian : sudo apt-get install gcc g++ make gawk bison parted texinfo flex btrfs-tools vim git lvm2
    * Fedora : sudo dnf install gcc g++ make gawk bison parted texinfo flex btrfs-tools vim git lvm2

1. git clone https://github.com/PhysixProject/physix.git
   cd physix

2. Edit physix.conf: Set your mandatory configs. 
    CONF_SKIP_PARTITIONING=y
    CONF_UEFI_ENABLE=
    CONF_ROOT_DEVICE=
    CONF_UEFI_DEV_PART=
    CONF_BOOT_DEV_PART=
    CONF_INSTALL_DEV_PARTITION=

   NOTE_2: Verify '/sbin' is in your environment PATH.
           echo $PATH | grep '\/sbin'

3. Set up the disk volumes by running:
     ./catalyst -i physix.conf
   NOTE: This will move this git repository to /mnt/physix/opt/admin/physix

4. Run build script.
     cd /mnt/physix/opt/admin/physix ; ./BUILD_BASE_SYSTEM.sh

5. Configure bootloader:
   Use your host system's grub.cfg as is, and add a Physix menu entry to it. A mock-up
   entry for this can be found at /boot/physix-grub.cfg. 

6. After reboot, `cd /opt/admin/physix;  ./BUILD_04-08.sh;` to build all packages.


Branches:
=========
* The 'mainline' branch is the bleeding edge of development. Use With Caution.

* The 'stable' branch should be considered as the latest and (least buggy) release branch.


Conceptual Project Design:
==========================
The system is devided into software groups. Software groups are collections
of source code which are compiled in order, so that all dependencies are met.
Software groups are defined as config files called recipes.

The system is built using a command line tool called 'catalyst', which
uses the recipes as its instructions.

 - Recipes:       JSON files which define information about all packages that
                  make up a software group. This includes md5sum of source code,
                  download URL, associated patches, license, and most importantly
                  the build script. The recipe names are prefixed by a number to
                  signify build order.

 - Build scripts: These are the command line instructions to build each software
                  project. These scripts are organized by the software group they
                  belong to in the build-scripts directory. Like the naming scheme
                  of the recipes, build scripts are also ordered by number for the same
                  reason.

When upgrading to a newer version of a source package, the recipe, build script, and
associated service configs are the key pieces to change.


What Physix Currently Provides:
==============================
 * catalyst: A command line tool used for building the system from config
   files / build-recipes. Read the recipe files for information about what software
   it builds and installs.

 * A minimal base system, built from recipes: 01-toolchain.json, 02-base-system.json,
   and 03-config-base.json

*  File System Snapshots: The default file system is Btrfs which provides snapshots
   of the file system's state to be recorded. This allows for returning the system
   to a previously known state.

 * Standard Utilities built from: 04-utilities.json

 * System Services:  05-services.json

 * System Testing: 05-testing.json

 * adjunct branch:
    - X Windows Display server: 05-xorg.json
    - Display Manager: 06-lightdm.json
    - Lightweight X11 Desktop Environment (LXDE): 07-lxde.json
    - X11 Applications: 08-xapps.json


Estimated Build Time:
=====================
To provide an idea of the time required to build each software
group, these estimates were collected using a system running
an Intel i7-4790 (4 Core, 2 threads/core) with 32G memory.

01-toolchain.json   :  50 Minutes
02-base-system.json : 168 Minutes
03-config-base.json :   5 Minutes
04-utilities.json   : 130 Minutes
05-services.json    :   2 Minutes
05-xorg.json        :  36 Minutes
06-lightdm.json     :  19 Minutes
07-lxde.json        :   4 Minutes
08-Xapps.json       :  80 Minutes
----------------------------------
Summation           :  ~8.25 hours


Installation (To separate storage device):
=============

   Prequisites:
	P0: Since there is not YET a bootable ISO image, a host system is required to 
            install from. During development, Debian 10.2 and Fedora 30 was used 
            extensively, and thus is recommended. See LFS host requirements for more
            specific requirements. 
            http://www.linuxfromscratch.org/lfs/view/stable-systemd/chapter02/hostreqs.html

	P1: i386 and/or x86_64 CPU

	P2: 62 Gigabytes of blank storage space. Storage volumes sizes can be adjusted in 
            physix.conf, however, keep in mind that file systems have organizational
            overhead, so available space will not be exact.

	P3: No existing partitions/volumes should be present on the storage device. 

    P4. verify '/sbin' is in your environment PATH.
        echo $PATH | grep '\/sbin'
        If not, set it in root user's .bashrc

   Device Setup: 
		If your target installation device is NOT blank, use the following steps to remove existing 
        partitions and volumes from the device. If your device is already blank, skip the Device Setup steps
        and go to the Build Configuration steps.
         
        D0: Use the 'lsblk' tool to view the device tree.
	    The following example shows output of the 'lsblk' tool, depicting the host system's
                device (sda) and the target installation device (sdb).


		NAME                           MAJ:MIN RM   SIZE  RO TYPE MOUNTPOINT
		sda                              8:0     0 465.8G  0 disk
		├─sda1                           8:1     0   512M  0 part /boot/efi
		├─sda2                           8:2     0   244M  0 part /boot
		└─sda3                           8:3     0   465G  0 part
		  ├─debian--vg-root              254:0   0  23.3G  0 lvm  /
		  ├─debian--vg-swap_1            254:1   0  31.9G  0 lvm  [SWAP]
		  ├─debian--vg-var               254:8   0   9.3G  0 lvm  /var
		  ├─debian--vg-tmp               254:9   0   1.9G  0 lvm  /tmp
		  └─debian--vg-home              254:10  0 398.7G  0 lvm  /home
		sdb                               8:16   0 232.9G  0 disk
		├─sdb1                            8:17   0   600M  0 part
		├─sdb2                            8:18   0     1G  0 part
		└─sdb3                            8:19   0 231.3G  0 part
		  └─EMG-data                   253:2    0 145.6G  0 lvm

		In the preceding example, notice the following information: 
                1. The names of the storage devices on the system (sda, sdb).
                2. The existing partitions on each device (sda1, sda2, sda3, sdb1, sdb2, sdb3).
                3. The lvm volumes located on the third partition of each device
                   (debian--vg... for sda3, and EMG-data for sdb).
                4. The mountpoints suggest the system is currently running Debian.



	  D1:
          ******** !USE EXTREME CAUTION! *************************************************
	      The following operations will destroy all existing data on your target 
          installation device.
          ********************************************************************************

	     Use the 'lvremove' tool to remove all volumes from your target installation device.
              For example, to remove all volumes from device sdb: 
                $# lvremove EMG

	      In the preceding example, this would remove all volumes under the EMG volume group.

            D2: Use the 'parted' tool to delete all remaining partitions.
              For example, to delete all partitions from device sdb:
                $# parted /dev/sdb rm 1
                $# parted /dev/sdb rm 2
                $# parted /dev/sdb rm 3

               Running lsblk again should show nothing under the sdb device.


   Build Configuration:

        B0: Edit the physix.conf file. Most values can be left to default, with the exception
            of those labeled as 'MANDATORY CONFIGS'. An example physix.conf can be found in
            Documentation/physix.conf-EXAMPLE

            CONF_SKIP_PARTITIONING=

            CONF_ROOT_DEVICE=  
                Device NAME in which the new system will be installed. In reference to the
                above example, this would be set to 'sdb'.

            CONF_INSTALL_DEV_PARTITION= 
                This defines the 'device' and 'partitionn number', where the 
                root system will live.
			    This should be the same as CONF_ROOT_DEVICE suffixed by a partition number.

            CONF_UEFI_ENABLE=
            CONF_UEFI_DEV_PART=
            CONF_BOOT_DEV_PART=

            CONF_GRUB_SET_ROOT=  
                This option specifies the name and partition used to configure
                the GRUB bootloader. It is IMPORTANT to set this correctly.
                It usually takes the form of '(hd0,2)', which indicates
                Storage Disk 1, Partition 2. This config/value is defined
                by your systemd BIOS, so if unsure, consult the BIOS config.

            CONF_GEN_USER=  
                Login name of the a general user other than root, to be
                created during installation

            CONF_IP_ADDRESS= 
                IP Address of the system at first boot.

            CONF_NAMESERVER= 
                IP Address of DNS server

            CONF_DEFAULT_ROUTE= 
                IP Address of your local network's router



   System Build:

       S0. Partition Disk:
           catalyst -i physix.conf
           cd /mnt/physix/opt/admin/physix

           To reduce the need to babysit the build, you can skip steps
           S1, S2, and S3 by running: BUILD_BASE_SYSTEM.sh

       S1. Build the temporary toolchain:
           - Pull/Download sources:
             catalyst -p 01-toolchain.json
           - Compile toolchain
             catalyst -t 01-toolchain.json

       S2. Build the base systemd:
           - Pull/Download sources:
             catalyst -p 02-base-system.json
           - Compile Base system
             catalyst -s 02-base-system.json

       S3. Configure the base system:
           catalyst -p 03-config-base.json
           catalyst -c 03-config-base.json

       S4. Reboot into your new base system, log in as root

       S5. [Recommended] If the system was built using btrfs, it is a good
           idea to take a snapshot of your system's current state. This will
           enable you to revert the system back to this point later.
           catalyst -r <SNAPSHOT-NAME>

       S6. Setup your system's PKI configuration:
           make-ca -g

       S7. Build the utilities software group.
           cd /opt/admin/physix
           catalyst -p 04-utilities.json
           catalyst -b 04-utilities.json


Contributions:
==============
Contributions are very welcome! :)
Please open an issue/task on github.
See TODO for what is needed.