2) Tutorials

Creation

This tutorial is for those who don't want to do any manual configuration, just a simple isolated chroot container. Take a look at the options for ChArch with charch -h if you'd like to try more advanced configurations.

Let's start!

1. First, find the rootfs tarball of your choice for your desired distro. For this example, we will be using the ARM Arch Linux rootfs tarball from the official mirrors.

2. With root permissions, type charch -n -u <url>. For an aarch64 device, the command would look like charch -n -u "http://os.archlinuxarm.org/os/ArchLinuxARM-aarch64-latest.tar.gz". This will fetch the latest rootfs tarball from Arch Linux directly and automatically configure and enter it. If all goes well, you should be logged in as root in your Arch Linux instance. Note that on your next login, you will not need the -n or -u options, as your rootfs instance has already been created. If you get an error, head over to issues and provide a log to find help on fixing the bug.

3. The first thing you may want to do is update your packages. Type pacman -Syu and confirm your upgrades. If you are using the bootstrap rootfs tarball, this may not work as your pacman repositories are not setup. You will need to configure this manually.

4. Once you are finished in your Arch Linux instance, type exit to return to your host terminal.

5. You may want to unmount your host partitions from the Arch Linux instance. Type unarch to kill any running processes and proceed with the unmount. If you receive an error stating that the unmount failed, you may need to either manually kill any running processes in the Arch Linux instance, or reboot your host device to kill everything and unmount automatically.

Removal

To remove a rootfs instance, simply type rmarch. If you want to specify a rootfs name, use rmarch <name>. To remove just the rootfs tarball, use rmarch -t. To remove your entire chroot container folder, type rmarch -a (NOTE: all rootfs instances must be removed prior to running this command).

Sideloading

If you have a custom rootfs tarball that you want to use, but don't want to specify a URL to charch, you can manually sideload a tarball.

1. Navigate to your chroot container of choice. The default is /home/chroot for Linux and /data/local/chroot/ for Android.
2. Remove any existing rootfs.tar.gz using rmarch -t.
3. Copy your rootfs tarball to rootfs.tar.gz (the final file should look like /home/chroot/rootfs.tar.gz).
4. Type charch -n <name> to create a rootfs instance called name that will use your custom tarball.
5. Type rmarch -t to remove your custom tarball.

If your image is already extracted, or you'd like to sideload a premade rootfs, you can follow these steps.

1. Navigate to your chroot container of choice. The default is /home/chroot for Linux and /data/local/chroot/ for Android.
2. Copy your extracted rootfs here (the final folder could look like /home/chroot/custom/).
3. You can directly enter the rootfs using charch <foldername> (the command could look like charch custom).

(Android) Using External Drives

Some power users may prefer to keep their ChArch folder on a MicroSD card or a USB OTG flash drive. There are a few steps we need to take.

1. First we need to figure out which device our external drive is on. With your drive unplugged, type blkid as root. Then plug in your drive, and type it again. You should see a new entry show up at the very bottom. It might look something like /dev/block/sda, or maybe /dev/block/sdg. Keep this path in your memory for later.
2. For chroot to work, your drive must be formatted as a UNIX compatible filesystem. The most popular choices are ext4 and f2fs. If your device kernel supports f2fs, I'd suggest using it since it is optimized for flash storage. However, if you are in need of compatibility (i.e. using this ChArch external drive on older devices), I'd suggest ext4, as all Android devices support it. Type mkfs.ext4 -f /dev/block/***, where *** is specific to your device. Replace mkfs.ext4 with mkfs.f2fs if you chose to use f2fs instead of ext4.
3. Now, we need to mount the drive. Type mount /dev/block/*** /mnt, replacing *** with the device specific hardware ID (obviously).
4. Time to create your ChArch directory! Type charch -n -d /mnt -u <url>, similar to the steps in the tutorial. Note the -d /mnt, where /mnt is the path to your mounted external drive. ChArch commands will need a -d option if you want it to execute them with respect to an external drive.
5. To unmount your rootfs instance, we'll use a similar process to Step #4. Type unarch -d /mnt.
6. To unmount your external drive completely, we need to unmount it from the /mnt folder. Type umount /mnt.