156 lines
5.4 KiB
Groff
156 lines
5.4 KiB
Groff
|
.\" Text automatically generated by txt2man
|
||
|
|
.TH clean-chroot-manager 1 "19 June 2025" "" ""
|
||
|
|
.SH NAME
|
||
|
|
\fBClean-chroot-manager \fP- Wrapper script to manage chroots when building packages under Arch Linux.
|
||
|
|
\fB
|
||
|
|
.SH DESCRIPTION
|
||
|
|
ccm provides a "one-click" solution for building packages in a clean chroot. Two key points that differentiate using ccm from the using the arch-build-scripts alone:
|
||
|
|
.IP \(bu 3
|
||
|
|
ccm automatically manages a local "staging" repo, so anything you build (dependencies from the AUR or more current versions of repo packages, etc.) are transparently pulled from that local repo.
|
||
|
|
.IP \(bu 3
|
||
|
|
ccm can optionally build with distcc and ccache.
|
||
|
|
.PP
|
||
|
|
To expand on point 1: let's say that we want to build a package called "bar" from the AUR but bar has a build dependency of another AUR package called "foo." Rather than first building foo, then installing foo, then building bar, and finally removing foo, the local repo will save a copy of the foo package which is indexed automatically therein. Pacman within the chroot is aware of the foo package thanks to the local repo. When we try to build bar, pacman silently grabs the foo package from the local repo as it would any other dependency.
|
||
|
|
.PP
|
||
|
|
To expand on point 2: distcc allows one to distribute compilation tasks to other PCs on the network to build packages faster. So long as distcc is properly setup, ccm can build using it, and again, this will be a "one-click" operation from the user's prospective. For more on distcc and how to setup using it under Arch, see the wiki page: https://wiki.archlinux.org/index.php/Distcc
|
||
|
|
.SH SETUP
|
||
|
|
$XDG_CONFIG_HOME/clean-chroot-manager.conf (referred to as "the config file" hereafter) will be created on the first invocation of ccm and contains all user managed settings. Edit this file prior to running ccm a second time. Make sure the user running ccm has sudo rights to execute /usr/bin/clean-chroot-manager or /usr/bin/ccm.
|
||
|
|
.SH USAGE
|
||
|
|
sudo ccm [option]
|
||
|
|
.SH OPTIONS
|
||
|
|
.TP
|
||
|
|
.B
|
||
|
|
a
|
||
|
|
Add any packages in the current directory to the local repo without building them. Useful if you already built something and simply want to copy it in the local repo.
|
||
|
|
.TP
|
||
|
|
.B
|
||
|
|
c
|
||
|
|
Create the chroot.
|
||
|
|
.TP
|
||
|
|
.B
|
||
|
|
cd
|
||
|
|
Create the chroot with distcc enabled. This is a shortcut/override for defining USE_DISTCC in the config file.
|
||
|
|
.TP
|
||
|
|
.B
|
||
|
|
d
|
||
|
|
Delete selected packages in the local repo.
|
||
|
|
.TP
|
||
|
|
.B
|
||
|
|
l
|
||
|
|
List the contents of the local repo (i.e. the packages built to date) should any exist.
|
||
|
|
.TP
|
||
|
|
.B
|
||
|
|
N
|
||
|
|
Nuke the chroot and external repo (if defined).
|
||
|
|
.TP
|
||
|
|
.B
|
||
|
|
n
|
||
|
|
Nuke the chroot (delete it and everything under it).
|
||
|
|
.TP
|
||
|
|
.B
|
||
|
|
p
|
||
|
|
Preview settings. Show some bits about the chroot itself.
|
||
|
|
.TP
|
||
|
|
.B
|
||
|
|
pc
|
||
|
|
Purge cache. Delete all files in the CCACHE_DIR (optional if building with ccache).
|
||
|
|
.TP
|
||
|
|
.B
|
||
|
|
S
|
||
|
|
Run makepkg but do not clean. Useful if building a series of packages with highly similar deps.
|
||
|
|
.TP
|
||
|
|
.B
|
||
|
|
s
|
||
|
|
Run makepkg. The equivalent of `makepkg \fB-s\fP` in the chroot.
|
||
|
|
.TP
|
||
|
|
.B
|
||
|
|
R
|
||
|
|
Repackage the current package if built. The equivalent of `makepkg \fB-sR\fP` in the chroot.
|
||
|
|
.TP
|
||
|
|
.B
|
||
|
|
t
|
||
|
|
Toggle [*\fB-testing\fP] on/off in the chroot. This function will enable or disable the testing repos in the chroot and also take care of upgrading/downgrading any affected packages.
|
||
|
|
.TP
|
||
|
|
.B
|
||
|
|
u
|
||
|
|
Update the packages within the chroot. The equivalent of `pacman \fB-Syu\fP` in the chroot.
|
||
|
|
.SH TIPS
|
||
|
|
.IP \(bu 3
|
||
|
|
Since ccm requires sudo rights, consider making an alias in ~/.bashrc or the like. For example: alias ccm='sudo ccm'
|
||
|
|
.IP \(bu 3
|
||
|
|
If you have multiple PCs on your LAN, consider having them help you compile via distcc which is supported within ccm. See $XDG_CONFIG_HOME/clean-chroot-manager.conf for setup instructions.
|
||
|
|
.IP \(bu 3
|
||
|
|
If your machine has lots of memory (>16G is probably the minimum), consider locating the chroot to a tmpfs partition to minimize access times and avoid disk usage. Know that all data will be lost upon a reboot and that some builds require lots of space so take care when considering it.
|
||
|
|
.PP
|
||
|
|
One way is to simply define a directory to mount as tmpfs like so in /etc/fstab:
|
||
|
|
.PP
|
||
|
|
.nf
|
||
|
|
.fam C
|
||
|
|
tmpfs /scratch tmpfs nodev,size=20G 0 0
|
||
|
|
|
||
|
|
.fam T
|
||
|
|
.fi
|
||
|
|
In order to have the expected CHROOTPATH directories created, we can use a systemd tmpfile like so:
|
||
|
|
.PP
|
||
|
|
.nf
|
||
|
|
.fam C
|
||
|
|
/etc/tmpfiles.d/ccm_dirs.conf
|
||
|
|
d /scratch/.chroot 0750 foo users -
|
||
|
|
|
||
|
|
.fam T
|
||
|
|
.fi
|
||
|
|
.SH USAGE EXAMPLES
|
||
|
|
Create a chroot:
|
||
|
|
.PP
|
||
|
|
.nf
|
||
|
|
.fam C
|
||
|
|
$ sudo ccm c
|
||
|
|
|
||
|
|
.fam T
|
||
|
|
.fi
|
||
|
|
Attempt to build the package in the clean chroot. If successful, the package will be added to a local repo so that it will be available for use as a dependency for building other packages:
|
||
|
|
.PP
|
||
|
|
.nf
|
||
|
|
.fam C
|
||
|
|
$ cd /path/to/PKGBUILD
|
||
|
|
$ sudo ccm s
|
||
|
|
|
||
|
|
.fam T
|
||
|
|
.fi
|
||
|
|
List out the contents of the local repo assuming something has been built:
|
||
|
|
.PP
|
||
|
|
.nf
|
||
|
|
.fam C
|
||
|
|
$ sudo ccm l
|
||
|
|
|
||
|
|
.fam T
|
||
|
|
.fi
|
||
|
|
Deletes everything under the top level of the chroot effectively removing it from the system:
|
||
|
|
.PP
|
||
|
|
.nf
|
||
|
|
.fam C
|
||
|
|
$ sudo ccm n
|
||
|
|
|
||
|
|
.fam T
|
||
|
|
.fi
|
||
|
|
.SH NOTE ABOUT SIGNED PACKAGES
|
||
|
|
When GPGKEY= is defined in the config file, the system's pacman keyring will need to have the corresponding public key imported and signed.
|
||
|
|
.PP
|
||
|
|
.nf
|
||
|
|
.fam C
|
||
|
|
$ gpg --armor --export 1234ABCD > new.key
|
||
|
|
# pacman-key --import new.key
|
||
|
|
# pacman-key --lsign-key 1234ABCD
|
||
|
|
|
||
|
|
.fam T
|
||
|
|
.fi
|
||
|
|
.SH BUGS
|
||
|
|
.IP \(bu 3
|
||
|
|
Not really a bug, but know that if you modify your config file after you created a chroot, the changes will not be effective until you nuke and rebuild the chroot.
|
||
|
|
.PP
|
||
|
|
Discover a bug? Please open an issue on the project page linked below.
|
||
|
|
.SH ONLINE
|
||
|
|
Project page: https://github.com/graysky2/clean-chroot-manager
|
||
|
|
.SH AUTHOR
|
||
|
|
graysky (therealgraysky AT proton DOT me).
|