jmq
/
Documentation
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

CRUX 3.7 handbook - first draft

This commit is contained in:
John McQuah 2022-08-04 08:19:57 -04:00
parent 66b2428ee5
commit 3237cc270f
7 changed files with 1543 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
crux-wiki/Handbook3-7 Normal file
View File

@ -0,0 +1,10 @@
(:Description The handbook for CRUX 3.7:)
!Handbook for CRUX 3.7
(:toc:)(:num:)
(:include Handbook3-7-Intro:)
(:include Handbook3-7-Install:)
(:include Handbook3-7-Configuration:)
(:include Handbook3-7-Package:)
(:include Handbook3-7-Ports:)
(:include Handbook3-7-Appendix:)

194
crux-wiki/Handbook3-7-Appendix Normal file
View File

@ -0,0 +1,194 @@
! Appendix
!! Troubleshooting
Many common problems are answered in the FAQ document, so if you experience problems please check whether the
[[http://crux.nu/Main/Faq | CRUX FAQ]] contains answers to your questions already.
If you have further questions, there's a dedicated mailing list for CRUX, and an IRC channel. Actual information about these can be found on the [[Community]] page.
[[#grubcfg-manually]]
!! Writing a grub config file by hand
If %fn%grub-mkconfig%% does not work (eg., because you saved the kernel image under a non-standard name), a grub.cfg file can be created manually. For more information see the GRUB manual at [[http://www.gnu.org/software/grub/manual/]]. A simple example configuration might look like the following:
[@
# Display the menu for 10 seconds
set timeout=10
# Boot the first entry by default
set default=0
# Boot entries follow
# Default CRUX boot entry
menuentry "CRUX 3.7" {
linux (hd0,msdos2)/boot/vmlinuz-5.15.55 root=/dev/sda2 quiet
}
# Single-user recovery entry
menuentry "CRUX 3.7 single-user mode" {
linux (hd0,msdos2)/boot/vmlinuz-5.15.55 root=/dev/sda2 quiet single
}
# Memory test entry
menuentry "MemTest86+ 4.20" {
linux16 (hd0,msdos2)/boot/memtest86+-4.20.bin
}
@]
Save the manual configuration file as '''/boot/grub/grub.cfg'''.
[[#syslinux-install]]
!! SYSLINUX installation notes
The venerable bootloader LILO has been dropped as of CRUX version 3.7; most users will find it straightforward to adopt
GRUB instead. This section presents another option, the SYSLINUX bootloader.
!!! Precaution
Installing a new boot manager is like modifying the partition table using fdisk or installing a new system kernel. Please create a rescue boot disk first!
!!! Installation -- UEFI booting
If your motherboard supports the UEFI boot mode, then installation of syslinux is as simple as copying a few files to the
EFI system partition (mounted at %fn%/boot/efi%% in the example commands below) and writing a configuration that tells
syslinux where to find your kernel. First confirm that EFI variables are visible to the currently-running kernel; if you run
@@efivar -l@@ and see a list of %fn%universally-unique-identifier-VariableName%%s, then the following commands should be
sufficient.
$ mkdir -p /boot/efi/BOOT
$ cd /boot/efi/BOOT
$ cp /usr/share/syslinux/efi64/ldlinux.e64 .
$ cp /usr/share/syslinux/efi64/syslinux.efi BOOTX64.EFI
$ cp /usr/src/linux-5.15.55/arch/x86/boot/bzImage vmlinuz-5.15.55
$ vi syslinux.cfg
-> Remember to change %fn%/boot/efi%% to the actual mount point of your EFI system partition.
-> Observe that the EFI bootloader was given a generic name in the fourth line above. If you had saved it in
%fn%/boot/efi/BOOT%% using the original filename provided by the '''syslinux''' package, then it would have been
necessary to run @@efibootmgr@@ to inform the BIOS about this new bootloader-like object. See [[#EFI-stub-install | "EFI Stub installation"]] for an example of using @@efibootmgr@@ to create new boot entries.
-> The fifth command puts a copy of the kernel (renamed to show version information) in the working directory. The final
command starts the vi editor on a buffer that will be written to %fn%syslinux.cfg%%, which must contain a line giving the
path to the kernel image. See the [[#syslinux-cfg| "SYSLINUX configuration file template"]] for details.
!!! Installation -- Legacy (BIOS) booting
If your motherboard does not support UEFI boot mode (or if you disabled it deliberately), then installing syslinux will
require you to overwrite the master boot record (MBR). The '''syslinux''' package provides two different binary
blobs that can occupy the designated MBR area of the hard disk. To determine which binary blob is appropriate, you will
need to remember what kind of partition table you wrote when you initialized your disk for CRUX. The older DOS (MBR)
partition table is supported by %fn%/usr/share/syslinux/mbr.bin%%, while the newer GPT (GUID) partition table is supported
by %fn%/usr/share/syslinux/gptmbr.bin%%. You can run @@fdisk -l /dev/sda@@ (replacing ''sda'' with your actual device) to
remind yourself what the existing partition table looks like. An identification of the exact partition type (DOS or GPT)
will appear next to ''Disklabel type:'' in the fdisk output.
Once you determine the binary blob that will work with your partition table, run the commands that will copy that
binary blob into the master boot record. '''Remember to replace ''sda'' with your actual device.'''
$ PTYPE=$(fdisk -l /dev/sda | grep "^Disklabel type" | cut -d " " -f3)
$ [ "$PTYPE" = "gpt" ] && BINBLOB=gptmbr.bin || BINBLOB=mbr.bin
$ mkdir -p /boot/efi/BOOT
$ cd /boot/efi/BOOT
$ cp /usr/share/syslinux/ldlinux.c32 .
$ extlinux --install /boot/efi/BOOT/
$ dd bs=440 count=1 conv=notrunc if=/usr/share/syslinux/$BINBLOB of=/dev/sda
$ vi syslinux.cfg
-> The @@extlinux@@ command takes a ''directory of the mounted EFI system partition'' as its argument, rather
than a device node. Upstream documentation begins with an example of calling the @@syslinux@@ command with the
''device node'' as its argument, which assumes that the EFI system partition is not mounted. Because you're already
creating files on this partition, we prefer the command that won't require you to unmount the partition before running it.
The @@extlinux@@ command is also smart enough to set its argument (the ''install target'') as the directory to be searched
for configuration files, so you can proceed to launch the editor on %fn%syslinux.cfg%% (see the next section for a
template) without changing directory.
[[#syslinux-cfg]]
!!! Template for a SYSLINUX configuration file
Now that the SYSLINUX bootloader is successfully installed, you need to tell it where to find your kernel and the root
filesystem.
[@
default CRUX-3.7
prompt 1
timeout 10
label CRUX-3.7
say "Now booting into CRUX"
kernel vmlinuz-5.15.55
append root=/dev/sda2 rw quiet
@]
When giving the location of a kernel image, relative paths are interpreted in reference to the %fn%syslinux.cfg%% file. In
the example above, where @@extlinux@@ assigned %fn%/boot/efi/BOOT/%% as the preferred location for %fn%syslinux.cfg%%, the
kernel would have to be copied to %fn%/boot/efi/BOOT/vmlinuz-5.15.55%%. Saving kernels here (in the BOOT subdirectory of
the EFI system partition) is a common practice when using the kernel itself as a bootloader; see the next section for more
details.
[[#EFI-stub-install]]
!! EFI Stub installation notes
GRUB and SYSLINUX offer the most familiar experience for users coming from LILO. After a one-time interaction with the
BIOS and the Master Boot Record, all subsequent updates to the GRUB or SYSLINUX configuration only involve editing a
flat-text file, and the contents of the bootsector or the NVRAM never need to be revisited. But if you aren't intimidated
by the prospect of manipulating EFI variables directly, another option is to let the Linux kernel image provide the EFI
bootloader code itself.
-> Note: this type of booting only works in UEFI mode, and when your kernel has been built with ''CONFIG_EFI_STUB=y''.
Legacy MBR booting is not supported with this method.
As with GRUB and SYSLINUX, the kernel has to be told which device to use as a root filesystem. Most modern BIOSes allow
you to append options like ''root=/dev/sda2'' to the line that boots the kernel, but some buggy UEFI implementations do
not honor such appended options. To be safe, you can customize the boot options during the kernel configuration process
(the @@make menuconfig@@ step), at the expense of making it harder to put the disk in an external enclosure and boot from
USB (when you want to travel lightly). If you leave the boot options empty during kernel configuration, and the BIOS does
not honor your appended options, you might have to boot from a rescue disk to get back into your system and fix things.
* Copy your built kernel to the BOOT subdirectory of the EFI system partition (mounted at %fn%/boot/efi%%). For maximum
compatibility, save it with the extension %fn%.efi%%.
[@
$ mkdir -p /boot/efi/BOOT
$ cd /boot/efi/BOOT
$ cp /usr/src/linux-5.15.55/arch/x86/boot/bzImage vmlinuz-5.15.55.efi
@]
* Next, create a boot entry telling the BIOS about the kernel image you just saved.
$ efibootmgr -c -d /dev/sda -L 'Linux 5.15.55' -l '\BOOT\vmlinuz-5.15.55.efi' -u 'root=/dev/sda2'
* Finally, change the boot order so that the newly-created boot entry is the first one tried. Start by finding the number
assigned to the newly-created entry, and then use that number to specify the desired boot order.
[@
$ efibootmgr
BootCurrent: 0000
Timeout: 1 seconds
BootOrder: 0000,0001
Boot0000* Linux 5.15.26 HD(1,GPT,d5a44413-5bea-b24c-b4b7-76b32d5d2ed4,0x800,0x64000)/File(\BOOT\vmlinuz-5.15.26.efi)72006f006f0074...
Boot0001* Linux 5.15.55 HD(1,GPT,d5a44413-5bea-b24c-b4b7-76b32d5d2ed4,0x800,0x64000)/File(\BOOT\vmlinuz-5.15.55.efi)72006f006f0074...
$ efibootmgr -o 0001,0000
@]
[[#initramfs]]
!! Notes on Initramfs
A common scenario that prevents the usual practice of booting a slimmed-down kernel containing only the drivers for the
root filesystem (and then loading modules to initialize other hardware) is that the root filesystem is not a physical
volume, but rather a logical volume inside an encryption layer like LUKS. To handle this situation, you will need to go
beyond the kernel building process outlined above, and also create a compressed filesystem image (called an ''initramfs'')
that contains the lvm and cryptsetup packages (and the drivers for usb input devices, if you chose not to compile them
into the kernel). Creating such an initramfs was once an intricate procedure, but tools like '''dracut''' make it much
simpler these days.
If running @@dracut@@, and saving the initramfs alongside the kernel in the EFI system partition, had been the only
deviations from the usual CRUX installation procedure, then one section of the appendix would suffice to explain how to do
full-disk encryption in CRUX. But preparation for this setup begins at the partitioning stage, when you need to call
commands from the '''lvm2''' and '''cryptsetup''' packages before creating and mounting your filesystems. So this section
of the appendix just points to a separate document, where an
[[https://gitlab.com/SiFuh/Documentation/-/blob/master/CRUX-3.6-Encrypted.txt | outline for installing CRUX with full-disk
encryption]] is given from beginning to end. Even if full-disk encryption is not your desired endpoint and you just want
to learn more about highly-modular kernel configs, the creation of an initramfs is best viewed in the context of the
overall installation procedure, after having successfully built some less-modular kernels yourself. Studying the upstream
documentation for any unfamiliar command in the linked outline (eg., %fn%cryptsetup%%, %fn%pvcreate%%, or %fn%dracut%%)
is an excellent way to distinguish the functions performed by the various components.

248
crux-wiki/Handbook3-7-Configuration Normal file
View File

@ -0,0 +1,248 @@
! Configuration
!! Initialization Scripts
!!! Runlevels
The following runlevels are used in CRUX (defined in %fn%/etc/inittab%%).
||cellpadding="3" rules="all" frame="box"
||! Runlevel ||! Description
||0 ||Halt
||1 (S) ||Single-user Mode
||2 ||Multi-user Mode
||3-5 ||(Not used)
||6 ||Reboot
!!! Layout
The initialization scripts used in CRUX follow the BSD-style (as opposed to the SysV-style) and have the following layout.
||cellpadding="3" rules="all" frame="box"
||! File ||! Description
||%fn%/etc/rc%% ||System boot script
||%fn%/etc/rc.single%% ||Single-user startup script
||%fn%/etc/rc.modules%% ||Module initialization script
||%fn%/etc/rc.multi%% ||Multi-user startup script
||%fn%/etc/rc.local%% ||Local multi-user startup script (empty by default)
||%fn%/etc/rc.shutdown%% ||System shutdown script
||%fn%/etc/rc.conf%% ||System configuration
||%fn%/etc/rc.d/%% ||Service start/stop script directory
Modify %fn%/etc/rc.modules%%, %fn%/etc/rc.local%% and %fn%/etc/rc.conf%% according to your needs.
!!! [[#ConfigurationVariables]] Configuration Variables in /etc/rc.conf
The following configuration variables are found in %fn%/etc/rc.conf%%.
(:table cellpadding="3" rules="all" frame="box":)
(:cell align=center:)'''Variable'''
(:cell align=center:)'''Description'''
(:cellnr valign=center:)FONT
(:cell:)
Specifies which console font to load at system startup. The contents of this variable will be passed as argument to '''setfont(1)'''. The available fonts are located in %fn%/usr/share/kbd/consolefonts/%%.
[-Example:-] @@FONT=default@@
(:cellnr valign=center:)KEYMAP
(:cell:)
Specifies which console keyboard map to load at system startup. The contents of this variable will be passed as argument to '''loadkeys(1)'''. The available keyboard maps are located in %fn%/usr/share/kbd/keymaps/%%.
[-Example:-] @@KEYMAP=sv-latin1@@
(:cellnr valign=center:)TIMEZONE
(:cell:)
Specifies the timezone used by the system. The available zone description files are located in %fn%/usr/share/zoneinfo/%%.
[-Example:-] @@TIMEZONE=Europe/Stockholm@@
(:cellnr valign=center:)HOSTNAME
(:cell:)
Specifies the hostname.
[-Example:-] @@HOSTNAME=pluto@@
(:cellnr valign=center:)SYSLOG
(:cell:)
Specifies the system logging daemon(s) to run at startup.
[-Example:-] @@SYSLOG=sysklogd@@
(:cellnr valign=center:)SERVICES
(:cell:)
Specifies which services to start at system startup. The services specified in this array must have a matching start/stop script in %fn%/etc/rc.d/%%. When entering multi-user mode the specified scripts will be called in the specified order with the argument '''start'''. At system shutdown or when entering single-user mode these scripts will be called in the reverse order with the argument '''stop'''.
[-Example:-] @@SERVICES=(crond lo net sshd)@@
(:tableend:)
!!! [[#LocaleGeneration]] Generating locales
Starting with CRUX 2.5, glibc does not contain all possible locales anymore, thus you'll have to generate the locales you
need/use. To ensure proper operation of %fn%pkgmk%%, the locale C.UTF-8 is generated as part of the CRUX installation. Any
other desired locales must be created by the administrator. A typical setup for swedish users would use the following
commands, so replace @@sv_SE*@@ with the locale you want:
# localedef -i sv_SE -f ISO-8859-1 sv_SE
# localedef -i sv_SE -f ISO-8859-1 sv_SE.ISO-8859-1
# localedef -i sv_SE -f UTF-8 sv_SE.UTF-8
!!! Network Configuration
The network configuration is found in the service script %fn%/etc/rc.d/net%%. To enable this service you need to add net to the SERVICES array in %fn%/etc/rc.conf%%. By default this service script configures a dynamic IP address. Example:
[@
#!/bin/sh
#
# /etc/rc.d/net: start/stop network interface
#
# Connection type: "DHCP" or "static"
TYPE="DHCP"
# For "static" connections, specify your settings here:
# To see your available devices run "ip link".
DEV=enp11s0
ADDR=192.168.1.100
MASK=24
GW=192.168.1.1
# Optional settings:
DHCPOPTS="-h `/bin/hostname` -t 10"
case $1 in
start)
if [ "${TYPE}" = "DHCP" ]; then
/sbin/dhcpcd ${DHCPOPTS}
else
/sbin/ip addr add ${ADDR}/${MASK} dev ${DEV} broadcast +
/sbin/ip link set ${DEV} up
/sbin/ip route add default via ${GW}
fi
;;
stop)
if [ "${TYPE}" = "DHCP" ]; then
/sbin/dhcpcd -x
else
/sbin/ip route del default
/sbin/ip link set ${DEV} down
/sbin/ip addr del ${ADDR}/${MASK} dev ${DEV}
fi
;;
restart)
$0 stop
$0 start
;;
*)
echo "Usage: $0 [start|stop|restart]"
;;
esac
# End of file
@]
If you want to configure your system to use a static IP address, specify TYPE=static and the correct interface. You will also need to configure DNS settings in /etc/resolv.conf. Example:
[@
#!/bin/sh
#
# /etc/rc.d/net: start/stop network interface
#
# Connection type: "DHCP" or "static"
TYPE="static"
# For "static" connections, specify your settings here:
# To see your available devices run "ip link".
DEV=enp11s0
ADDR=192.168.1.100
MASK=24
GW=192.168.1.1
# Optional settings:
DHCPOPTS="-h `/bin/hostname` -t 10"
case $1 in
start)
if [ "${TYPE}" == "DHCP" ]; then
/sbin/dhcpcd ${DHCPOPTS}
else
/sbin/ip addr add ${ADDR}/${MASK} dev ${DEV} broadcast +
/sbin/ip link set ${DEV} up
/sbin/ip route add default via ${GW}
fi
;;
stop)
if [ "${TYPE}" == "DHCP" ]; then
/sbin/dhcpcd -x
else
/sbin/ip route del default
/sbin/ip link set ${DEV} down
/sbin/ip addr del ${ADDR}/${MASK} dev ${DEV}
fi
;;
restart)
$0 stop
$0 start
;;
*)
echo "Usage: $0 [start|stop|restart]"
;;
esac
# End of file
@]
[@
#
# /etc/resolv.conf: resolver configuration file
#
search your internal domain>
nameserver your DNS server>
# End of file
@]
To associate with a password-protected wireless network, you should first create a configuration file for
%fn%wpa_supplicant%% to use, then launch wpa_supplicant on that interface.
$ wpa-passphrase MYNETWORK MYPASSWORD > /etc/wpa_supplicant-wlan0.conf
$ wpa_supplicant -i wlan0 -c /etc/wpa_supplicant-wlan0.conf
-> Replace '''wlan0''' with the name of your actual network interface. Run %fn%ip link%% to see the list of all available
interfaces.
If the %fn%wpa_supplicant%% output indicates a successful authentication, you can background the process and run
%fn%dhcpcd wlan0%% to request an address from the DHCP server.
The '''wpa_supplicant''' package provides two startup scripts in %fn%/etc/rc.d%%. You might choose to put '''wlan''' in the
SERVICES array of %fn%/etc/rc.conf%% (replacing '''net'''), which will let %fn%wpa_supplicant%% manage all your
network interfaces. Another option is to let the '''net''' startup script call %fn%wpa_supplicant%% as needed, by copying
into %fn%/lib/dhcpcd/dhcpcd-hooks/%% the example file %fn%/usr/share/dhcpcd/hooks/10-wpa_supplicant%%.
!! Passwords and User Environment
CRUX uses SHA512 passwords by default. To change the password encryption method set the ENCRYPT_METHOD variable in %fn%/etc/login.defs%% to DES, MD5 or SHA256.
Furthermore, when compiling programs that use the @@crypt(3)@@ function to authenticate users you should make sure that these programs are linked against the %fn%libcrypt%% library (i.e. use '''-lcrypt''' when linking) which contains the SHA512 version of the crypt function (this version is backwards compatible and understands DES passwords as well).
Also configurable in %fn%/etc/login.defs%% are the settings that govern how @@useradd(8)@@ behaves when you create a new
non-root user, such as CREATE_HOME and USERGROUPS_ENAB. First-time CRUX administrators might be surprised to learn that
creating a new user via %fn%useradd -m%% will not automatically populate the home directory with a basic shell
startup file, as happens on other Linux distributions whose %fn%/etc/skel/%% contains their idea of an initial home
directory. No such decisions are imposed on CRUX administrators, who get to work with the upstream tools in their
unmodified state.
The core packages '''linux-pam''' and '''dumb_runtime_dir''' provide a number of modules that can be loaded upon
successful login. The files in %fn%/etc/pam.d%% govern the association between the type of login (eg., tty, SSH, su, X
Display Manager) and the modules that get loaded (eg., pam_env, pam_exec, pam_limits). Read the manpage for any PAM module
of interest, to learn how it might be configured for your needs. Some typical situations that can be solved with PAM
modules are listed in the table below.
||cellpadding="3" rules="all" frame="box"
||! file in /etc/pam.d ||! Typical usage
||%fn%pam_env.so%% || export some mandatory environment variables, no matter what login shell the user has chosen
||%fn%pam_limits.so%% || increase the allowed number of opened files, to ensure proper operation of some games
||%fn%pam_xauth.so%% || grant another user access to the X display of the logged-in user, so that programs invoked with ''su'' can work properly
||%fn%pam_mount.so%% || automatically mount a LUKS-encrypted home partition
||%fn%pam_dumb_runtime_dir.so%% || create an XDG_RUNTIME_DIR for applications that conform to the freedesktop.org specification
!! Upgrading the Kernel
The kernel source, which is found in %fn%/usr/src/linux-5.15.x/%% is not installed using '''pkgadd'''. If you decide to
upgrade your kernel you can safely do so by manually replacing the kernel source with a newer version (or place it
somewhere else). This will not make the package database inconsistent (since it's not installed with '''pkgadd''') nor
will it affect the kernel headers found in %fn%/usr/include/linux%% and %fn%/usr/include/asm%% since these are not
symlinks to the kernel source, but instead contain copies of the headers.

261
crux-wiki/Handbook3-7-Install Normal file
View File

@ -0,0 +1,261 @@
! Installing CRUX
!! Supported Hardware / Requirements
Packages on the official CRUX ISO image are compiled with optimization for x86-64 (AMD Athlon 64, Intel Core, Intel Atom) or newer processors. Do not try to install it on an i686 (Pentium-Pro, Celeron, Pentium-III) or lower processor, since it simply will not work.
A minimum of 768MB system memory is required to install CRUX from a CD-ROM or removable flash drive. It is possible to perform a custom chroot installation with only 16MB of RAM.
The kernel used during installation, i.e. when booting from the CRUX ISO image (El Torito), is compiled with the following disk controllers and USB support:
||cellpadding="3" rules="all" frame="box"
||! Subsystem ||! Driver(s) included in bootkernel ||
||PATA/IDE||ALi, AMD/Nvidia, ARTOP 6210/6260, ATI, CMD64x, CS5510/30/35/36, Cypress CY82C693, EFAR SLC90E66, HPT 34x/36x/37x, ITE 8211/12/13, JMicron, Marvell, NETCELL Revolution, Ninja32/Delkin, Nat Semi NS8741x, Intel PIIX/SCH/MPIIX, OPTI FireStar/621x, Promise, RADISYS 82600, SC1200, SERVERWORKS OSB4/CSB5/CSB6/HT1000, CMD / Silicon Image 680, SiS, Compaq Triflex, VIA, Winbond SL82C105, ISA Plug & Play, PC Tech RZ1000, Generic||
||SATA||AHCI, Intel ESB/ICH/PIIX, Initio 162x, Silicon Image/Silicon Image 31xx, Pacific Digital ADMA/QStor, Promise SX4/TX2/TX4, Marvell, Nvidia, SiS 180/96x, Broadcom/ServerWorks/Apple K2, ULi, VIA, Vitesse VSC7174/Intel 31244||
||SCSI/SAS||3Ware 5/6/7/8/9xxx, HP Smart Array, 7000FASST, ACARD, Adaptec AHA15xx/28xx, Adaptec AACRAID, Adaptec AIC7xxx/79xx/94xx, Adaptec I20, Marvell 88SE64xx/94xx, Advansys, Always IN2000, ARECA 11xx/12xx/13xx/16xx, LSI Logic New/Legacy/MegaRAID/MPT, HighPoint RocketRAID 3xxx/4xxx, BusLogic, VMware PVSCSI, DMX3191D, DTC 3x80, EATA, Future Domain 16xx/Adaptec AHA2920A, Intel/ICP, IBM ServeRAID/Power Linux, Initio 9100U/INI-A100U2W, NCR53c406a, Promise SuperTrak EX, SYM53C8xx, PAS16, Qlogic FAS, Qlogic QLA 1xxxx/2xxx, Qlogic ISP 4xxx/82xx, Emulex LightPulse FC, Symbios 53c416, Tekram DCxxx, Trantor Txxx, UltraStor, UltraStor 14F/34F||
||USB||EHCI HCD (USB 2.0) support, UHCI (Intel PIIX4, VIA, ...) support, OHCI (Compaq, iMacs, OPTi, SiS, ALi, ...) support, USB Mass Storage support, USB Human Interface Device (full HID) support, HID input layer support||
In order to install CRUX, your disk controller must be present in the list above. If your hardware is not supported or you have other problems installing CRUX, you might find a solution in the [[https://crux.nu/Wiki/HomePage | CRUX wiki]].
!! [[#InstallingFromCD-ROM]] Installing From optical medium or removable flash drive
Download the CRUX ISO image (%fn%crux-3.7.iso%%). To ensure that the download was successful, examine its checksum.
$ shasum -a 256 crux-3.7.iso
Compare the output with the file %fn%crux-3.7.sha256%%, which can be found
in the same directory as the ISO image on the download site. If the
checksums match, the download was successful and you can continue by burning
the ISO image to a DVD or writing it to a removable flash drive.
* The ISO image is bootable. After making sure that your BIOS gives priority
to optical drives or flash drives, just insert the newly-written DVD or
removable flash drive and reboot your computer. Press @@Enter@@ at the
boot prompt (you might have to adjust the @@root=@@ parameter, depending
on your hardware configuration).
* You will be logged in as '''root''' on tty1 ('''root''' has no password set).
* Create (if necessary) and format the partition(s) you want CRUX to be
installed on. Remember the choice you make for the filesystems (especially
root)! The driver for your chosen filesystem must be compiled into your
Linux kernel, or included on an initramfs.
$ fdisk /dev/sd?
$ mkfs.???? /dev/sd??
$ mkswap /dev/sd??
->%lfloat% http://crux.nu/doc/images/note.png
'''Note'''[[]]
->''Please keep in mind that SATA harddisks are usually detected as SCSI devices. The first SATA disk is called ''%fn%/dev/sda%%'' instead of ''%fn%/dev/hda%%''. For more information about harddisk naming conventions please refer to the [[http://www.tldp.org/HOWTO/Partition/devices.html | Linux Partition HOWTO]].''
The amount of disk space required depends on how many packages are selected to install. It is recommended to have at least a 1G root partition (CRUX will use about 200MB-500MB, depending on your configuration).
The amount of swap space required depends on several factors, including whether you intend to use hibernation or build new packages in RAM.
For more information about how memory is handled by modern Linux kernels, please refer to [[https://chrisdown.name/2018/01/02/in-defence-of-swap.html | In Defense of Swap]].
->%lfloat% http://crux.nu/doc/images/note.png
'''Note: UEFI'''[[]]
->''For UEFI installation a GPT disklabel and an EFI system partition (ESP) are required in most cases. The ESP does not need to be very large (100MiB for example) and should be formatted with a FAT32 filesystem and flagged as bootable. When using UEFI the boot loader/manager will be installed in the ESP rather than the traditional method of installation into the Master Boot Record (MBR).''
CRUX supports all the filesystems supported as root filesystems by the Linux kernel: btrfs, ext2, ext3, ext4, JFS, reiserfs and XFS.
Further, it is highly recommended to separate the system data from user data, i.e. use a separate partition for %fn%/home%% (and possibly %fn%/var%%) since that will make your life a lot easier the day you want to upgrade, reinstall or remove your system.
->%lfloat% http://crux.nu/doc/images/note.png
'''Note'''[[]]
->''Make sure the appropriate userspace filesystem tools are installed. xfsprogs, btrfs-progs, jfsutils and reiserfsprogs can be found in the opt repository.''
->%lfloat% http://crux.nu/doc/images/note.png
'''Note'''[[]]
->''Make sure that any BIOS Virus Protection option is DISABLED as this option may prevent '''fdisk''' from writing new partitions correctly.''
* Mount the partition on which you want to install this distribution.
$ mount /dev/sd?? /mnt
If you want the installation to span more than one partition, mount those partitions as well. For example, if you want to have a different partition for %fn%/home%% or %fn%/var%%, then do:
$ mkdir /mnt/var
$ mount /dev/sd?? /mnt/var
* Activate your swap partition(s).
$ swapon /dev/sd??
* Type '''setup''' to start the package installation script. The script will ask where you mounted your new root partition and which packages you want to install. Select the packages you wish to install; it is recommended to install all the packages from %fn%core%%.
->%lfloat% http://crux.nu/doc/images/note.png
'''Note: UEFI'''[[]]
->''If installing a UEFI system make sure to select the '''efibootmgr''' package from the '''opt''' collection during the package selection phase.''
'''efibootmgr''' would be installed automatically during dependency resolution if you chose ''grub2-efi'' as your boot loader, but it's a good idea to start your CRUX experience paying close attention to the administrative tools you'll be using.
'''Note: initramfs'''[[]]
->''If you plan to build a modular kernel, remember to select the
'''dracut''' package from the '''opt''' collection.''
After the packages have finished installing, the '''setup''' script will display an installation log. Make sure the last line in the log says @@“0 error(s)”@@.
If you missed or forgot to install certain packages, you can just mount the CRUX installation medium and use '''pkgadd''' to install them.
[[http://crux.nu/doc/screenshots.html | Screenshots of setup]]
* Now it's time to compile your kernel and do basic system configuration. The kernel compilation requires that you “chroot” into your new CRUX installation.
->%lfloat%http://crux.nu/doc/images/note.png
'''Note'''[[]]
->''There is a shortcut command for creating the chroot environment: %fn%setup-chroot%%. This will execute all these steps at once.''
$ mount --bind /dev /mnt/dev
$ mount --bind /tmp /mnt/tmp
$ mount --bind /run /mnt/run
$ mount -t proc proc /mnt/proc
$ mount -t sysfs none /mnt/sys
$ mount -t devpts -o noexec,nosuid,gid=tty,mode=0620 devpts /mnt/dev/pts
(UEFI only) $ mount --bind /sys/firmware/efi/efivars /mnt/sys/firmware/efi/efivars
$ chroot /mnt /bin/bash
* Set the root password.
$ passwd
* Edit %fn%/etc/fstab%% to configure your filesystem(s). Editors '''vim''' and '''nano''' are available. The fstab
installed by the '''setup''' script includes the most commonly-used mountpoints (commented out, of course), which can be
used as a reference when customizing fstab for your partition scheme.
-> '''udev''' ''reads files in'' %fn%/sys/*%% ''and'' %fn%/proc/*%%. ''Make sure that those pseudo filesystems are enabled
in your kernel configuration and available during system-startup. Also note that udev doesn't automatically mount''
%fn%/dev/pts%%. ''Terminal applications such as'' '''xterm(1)''' ''will not work if you forget to mount it. ''We highly
recommend you check that your %fn%fstab%% contains the following line:''
-> [@# dev> mountpoint> type> options> dump> pass>
[..]
devpts /dev/pts devpts noexec,nosuid,gid=tty,mode=0620 0 0
@]
* Edit %fn%/etc/rc.conf%% to configure font, keyboard, timezone, hostname and services. See Section [[#ConfigurationVariables | "Configuration Variables in /etc/rc.conf"]] for details about %fn%/etc/rc.conf%%.
* Generate locales for your system. See section [[#LocaleGeneration| "Generating locales"]] for more information.
* Edit %fn%/etc/rc.d/net%%, %fn%/etc/hosts%% and %fn%/etc/resolv.conf%% to configure your network (ip-address/gateway/hostname/domain/dns).
* Go to %fn%/usr/src/linux-5.15.x%%, configure and compile a new kernel.
->%lfloat%http://crux.nu/doc/images/note.png
'''Note'''[[]]
->Make sure to include drivers needed to bring up your root filesystem!
Unless you also create an initramfs with '''dracut''', ''these drivers must be
built-in and not kernel modules''. Look for sections titled "SCSI disk
support", "partition types", and "disk controller" when configuring your
kernel. For example:
* CONFIG_SATA_AHCI=y
* CONFIG_BLK_DEV_SD=y
* CONFIG_EXT4_FS=y
->%lfloat%http://crux.nu/doc/images/note.png
'''Note'''[[]]
->The setup program installs a configuration file
%fn%/usr/src/linux-5.15.x/.config%% which is a good starting point for a
custom kernel, because all needed options, like CONFIG_DEVTMPFS, are
enabled.
$ cd /usr/src/linux-5.15.x
$ make menuconfig
$ make all
$ make modules_install
[[#BootLoader-Setup]] Installing a Bootloader
-->If you plan to use syslinux as your bootloader, skip ahead to [[#syslinux-install | "syslinux installation notes"]]
in the appendix of this document. Otherwise, proceed with '''grub-install''' according to the instructions below.
First place a copy of the newly-compiled kernel in a standard location,
named so that it will be detected by %fn%grub-mkconfig%%. For example,
%fn%grub-mkconfig%% will be able to recognize '''/boot/vmlinuz-5.x''' as
a valid kernel image, but '''NOT''' a file named '''/boot/linuxkernel-5.x'''.
[@
$ cp arch/x86/boot/bzImage /boot/vmlinuz-5.15.55-1
$ cp System.map /boot
$ grub-mkconfig > /boot/grub/grub.cfg
@]
grub-mkconfig's output can be altered by setting variables in a
configuration file, '''/etc/default/grub'''. This file is NOT created by
default and is not required, but is useful for customizing the video
resolution and grub menu colors without crafting a '''grub.cfg''' by hand.
For more information, see the GRUB manual at
[[http://www.gnu.org/software/grub/manual/]].
* For legacy boot (not UEFI):
** Install grub2 into the Master Boot Record using the command
'''grub-install /dev/sd??'''.
-->Replace '''/dev/sd??''' with the actual node of the device whose Master Boot
Record you want to overwrite, eg., '''/dev/sda''' for the first SATA disk.
* For UEFI booting:
** Install grub2 into the ESP using the command '''grub-install /boot/efi'''.
-->Replace '''/boot/efi''' with the location of the mounted ESP. If '''efibootmgr''' was selected during the package selection phase grub-install will automatically create a boot entry and make it active.
** Check that the ESP now contains the grub bootloader, and that an entry
for the grub bootloader now appears in the EFI variables.
[@
$ ls /boot/efi/
$ efibootmgr
@]
-->More information about UEFI and other boot loader/manager options can be found in the CRUX wiki at [[https://crux.nu/Wiki/UEFI]].
* Remove the CRUX installation media from your computer and reboot from harddisk.
!! Upgrading From DVD-ROM or removable flash drive
Download the CRUX ISO image (%fn%crux-3.7.iso%%). To ensure that the download was successful, examine its checksum.
$ shasum -a 256 crux-3.7.iso
Compare the output with the file %fn%crux-3.7.sha256%%, which can be found in the same directory as the ISO image on the download site. If the checksums match, the
download was successful and you can continue by burning the ISO image to a DVD or writing it to a removable flash drive.
* The ISO image is bootable. After making sure that your BIOS gives priority
to optical drives or flash drives, just insert the newly-written DVD or removable flash drive and reboot your computer. Press @@Enter@@ at the boot prompt (you might have to adjust the @@root=@@ parameter, depending on your hardware configuration).
* You will be logged in as '''root''' on tty1 ('''root''' has no password set).
* Mount your CRUX root partition.
$ mount /dev/sd?? /mnt
If your installation spans over more than one partition, mount these partitions as well. For example, if you have a different partition for %fn%/var%%, then do:
$ mount /dev/sd?? /mnt/var
* Activate your swap partition(s).
$ swapon /dev/sd??
* Type '''setup''' to start the package installation script. The script will ask you where you mounted your root partition and which packages you want to upgrade. To avoid running into trouble (e.g. a new version of some library isn't 100% backwards compatible), it is a good idea to upgrade all packages.
->%lfloat%http://crux.nu/doc/images/note.png
'''Note'''[[]]
->''The '''setup''' script uses the %fn%/etc/pkgadd.conf%% of the target system to determine which files to upgrade, and which files not to upgrade. The files that are not upgraded are put in %fn%/var/lib/pkg/rejected/%% (Section [[#UpgradingaPackage | "Upgrading a Package"]]).''
When the '''setup''' script has upgraded the selected packages an upgrade log will be displayed. Make sure the last line in the log says @@“0 error(s)”@@. If you missed/forgot to install certain packages, you can just mount the CRUX installation media and use '''pkgadd''' to install them (e.g. '''pkgadd /mnt/crux/opt/package#1.0-1.pkg.tar.gz''').
* The already-built kernel from your previous CRUX installation might not be compatible with the newly-upgraded %fn%linux-firmware%% package. To be safe, you're advised to “chroot” into your CRUX installation and compile a fresh kernel from the latest source tree.
->%lfloat%http://crux.nu/doc/images/note.png
'''Note'''[[]]
->''There is a shortcut command for creating the chroot environment: %fn%setup-chroot%%. This will execute all these steps at once.''
$ mount --bind /dev /mnt/dev
$ mount --bind /tmp /mnt/tmp
$ mount --bind /run /mnt/run
$ mount -t proc proc /mnt/proc
$ mount -t sysfs none /mnt/sys
$ mount -t devpts -o noexec,nosuid,gid=tty,mode=0620 devpts /mnt/dev/pts
(UEFI only) $ mount --bind /sys/firmware/efi/efivars /mnt/sys/firmware/efi/efivars
$ chroot /mnt /bin/bash
* Generate locales for your system. See section [[#LocaleGeneration| "Generating locales"]] for more information.
* Go to %fn%/usr/src/linux-5.15.x%%, configure and compile a new kernel.
* Adjust %fn%/etc/fstab%% to reflect any changes made to your partition scheme since your earlier installation of CRUX.
See the notes about %fn%fstab%% in the [[#InstallingFromCD-ROM| "Installing"]] section.
-->More information about UEFI and other boot loader/manager options can be found in the CRUX wiki at [[https://crux.nu/Wiki/UEFI]].
* Remove the CRUX DVD-ROM from your drive and reboot from harddisk.

43
crux-wiki/Handbook3-7-Intro Normal file
View File

@ -0,0 +1,43 @@
[[Profiles.PerLiden | Per Lidén]] wrote this handbook. RobertMcMeekin converted it to DocBook, the [[About | CRUX team]] made a Wiki version. Numerous others have given feedback and improvement suggestions.
! Introduction
!! What is CRUX?
CRUX is a lightweight Linux distribution for the x86-64 architecture targeted at experienced Linux users. The primary focus of this distribution is "keep it simple",
which it reflects in a simple tar.gz-based package system, BSD-style initscripts, and a relatively small collection of trimmed packages. The secondary focus is
utilization of new Linux features and recent tools and libraries. CRUX also has a ports system which makes it easy to install and upgrade applications.
!! Why use CRUX?
There are many Linux distributions out there these days, so what makes CRUX such an appealing choice to its users?
The choice of distribution is a matter of taste, really. Here are a few hints about the tastes and goals of the people behind CRUX.
CRUX is made with simplicity in mind from beginning to end. Making it easy to create new and update old packages is essential; updating a package in CRUX is often
just a matter of typing %fn%sudo prt-get update $MYPKG%%.
The usage of ports helps keep your packages up to date; not the latest bleeding-edge-alpha version, but the latest stable version.
Other features include creating packages optimized for your processor, eg. by compiling with -march=x86-64, and avoiding cluttering the filesystem with files you'll never use, eg. /usr/doc/*, etc. If you need more information about a specific program, other than information found in the man-page, Google usually knows all about it.
Although CRUX strives to use new features as they become available, you will never have to deal with a frenzy of innovation that leaves you with an unrecognizable system. A CRUX user from the early years could abandon the distribution for two decades, then install the latest release and feel right at home.
In short, CRUX might suit you very well if you are:
* A somewhat experienced Linux user who wants a clean and solid Linux distribution as the foundation of your installation.
* Someone who does not hesitate to download and compile programs from the source.
* Someone who values consistency and stability in the essential components of the operating system.
%lfloat% http://crux.nu/doc/images/note.png
'''Note'''[[]]
''If you are using CRUX, we highly recommend to subscribing to our low-volume [[MailingLists | mailing list]] because security updates and updates that need user action are announced there.''
!!License
!!!Packages
Since CRUX is a Linux distribution, it contains software written by a lot of different people. Each software package comes with its own license, chosen by its author(s). To find out how a particular package is licensed, have a look at its source code.
!!! Build Scripts
All package build scripts in CRUX (in package categories %fn%core%%, %fn%opt%%, %fn%xorg%%, and %fn%compat-32%%) are Copyright © 2000-2022 by Per Lidén and the CRUX development team and are released under the
[[http://www.gnu.org/copyleft/gpl.html | GNU General Public License]].
!!! NO WARRANTY
CRUX is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. Use it at YOUR OWN RISK.

592
crux-wiki/Handbook3-7-Package Normal file
View File

@ -0,0 +1,592 @@
!The Package System
!!Introduction
The package system ([[http://crux.nu/Wiki/FaqPkgUtils | pkgutils]]) is made with simplicity in mind, where all packages are plain %fn%tar.gz files%% (i.e. without any kind of meta data).
Packages follow the naming convention %fn%''<name>#<version>-<release>''.pkg.tar.gz%%, where %fn%<name>%% is the name of the program, %fn%<version>%% is the version
number of the program, and %fn%<release>%% is the version number of the package. \\
The %fn%pkg.tar.gz%% extension is used (instead of just %fn%tar.gz%%) to indicate that this is not just any %fn%tar.gz%% file, but a %fn%tar.gz%% that is meant to be installed using '''pkgadd'''.
This helps distinguish packages from other %fn%tar.gz%% files.
Note that pkgmk nowadays supports additional compression schemes like bzip2 with the %fn%tar.bz2%% extension or XZ ending with %fn%tar.xz%%.
'''pkgadd(8)''', '''pkgrm(8)''', '''pkginfo(8)''', and '''pkgmk(8)''' are the package management utilities. With these utilities you can install, uninstall, inspect, make packages, or query the package database.
When a package is installed using '''pkgadd''' a new record is added to the package database (stored in %fn%/var/lib/pkg/db%%). The basic package system does not have
any kind of dependency checking, thus it will not warn you if you try to build a package that requires libraries or headers from other packages. Your mistake will
only be revealed when the pkgmk build function exits with errors. The included '''prt-get''' tool, however, can be told to resolve dependencies, if called with
'''prt-get depinst''' rather than simply '''prt-get install'''.
The following sections will in describe in short how to use the package utilities. Additional information about these utilities can be found on their respective man
pages.
!! Using the Package System
!!! Installing a Package
Installing a package is done by using '''pkgadd'''. This utility requires at least one argument, the package you want to install. Example:
$ pkgadd bash#5.0.18-1.pkg.tar.gz
When installing a package the package manager will ensure that no previously installed files are overwritten. If conflicts are found, an error message will be printed and '''pkgadd''' will abort without installing the package. The error message will contain the names of the conflicting files. Example:
$ pkgadd bash#5.0.18-1.pkg.tar.gz
bin/sh
usr/man/man1/sh.1.gz
pkgadd error: listed file(s) already installed (use -f to ignore and overwrite)
To force the installation and overwrite the conflicting files, you can use the option '''-f''' (or '''--force'''). Example:
$ pkgadd -f bash#5.0.18-1.pkg.tar.gz
The package system allows a file to be owned by exactly one package. When forcing an installation the ownership of the conflicting files will be transferred to the package that is currently being installed. Directories can however be owned by more then one package.
->%lfloat%http://crux.nu/doc/images/warning.png
'''Warning'''[[]]
->''It is often not a good idea to force the installation unless you really know what you are doing. If a package conflicts with already installed files it could be a sign that the package is broken and installs unexpected files. Use this option with extreme care, preferably not at all.''
As earlier, the package file itself does not contain any meta data. Instead, the package manager uses the package filename to determine the package name and version.
Thus, when installing a package file named %fn%bash#5.0.18-1.pkg.tar.gz%%, the package manager will interpret this as a package named %fn%bash%% at version %fn%5.0.18-1%%.
If '''pkgadd''' is unable to interpret the filename (e.g. # is missing or the filename does not end with %fn%.pkg.tar.gz%%) an error message will be printed and pkgadd will abort without installing the package.
!!! [[#UpgradingaPackage]] Upgrading a Package
Upgrading a package is done using '''pkgadd''' with the '''-u option'''. Example:
$ pkgadd -u bash#5.0.18-1.pkg.tar.gz
This will replace the previously installed %fn%bash%% package with the new one. If you have not previously installed %fn%bash%%, '''pkgadd''' will print an error message. The package system does not care about the version number of the package in that you can &#8220;upgrade&#8221; version 2.05-1 with version 2.04-1 (or even with version 2.05-1 itself). The installed package will be replaced with the specified package.
Upgrading a package is not simply a wrapper for '''pkgrm''' followed by '''pkgadd''', because you usually want to preserve
your customizations of the config and log files that are owned by the already-installed package. Therefore, @@pkgadd -u@@
conducts some upgrade-specific checks of the filesystem and the package database to construct what is called a '''keep
list''', in addition to the '''non-install list''' (which is initialized for every '''pkgadd''' transaction). The
construction of both lists is governed by the file %fn%/etc/pkgadd.conf%%.
%fn%/etc/pkgadd.conf%% can contain rules describing how '''pkgadd''' should behave when installing or
upgrading any package. A rule is built out of three fragments; ''event'', ''pattern'' and ''action''. The event names the
kind of operation (INSTALL or UPGRADE) to which this rule will be applied. The ''pattern'' is a filename pattern expressed
as a regular expression and the action applicable to the INSTALL or UPGRADE ''event'' is YES or NO. More than one rule of
the same event type is allowed, in which case the first rule will have the lowest priority and the last rule will have the
highest priority. Example:
[@
#
# /etc/pkgadd.conf: pkgadd(8) configuration
#
UPGRADE ^etc/.*$ NO
UPGRADE ^var/log/.*$ NO
UPGRADE ^etc/X11/.*$ YES
UPGRADE ^etc/X11/xorg.conf$ NO
# End of file
@]
The above example will cause '''pkgadd''' to never upgrade anything in %fn%/etc/%% or %fn%/var/log/%% (subdirectories
included), except files in %fn%/etc/X11/%% (subdirectories included), unless it is the file %fn%/etc/X11/xorg.conf%%. The
default rule is to upgrade everything, rules in this file are exceptions to that rule.
->%lfloat%http://crux.nu/doc/images/note.png
'''Note'''[[]]
->''A pattern should never contain an initial &#8220;/&#8221; since you are referring to the files in the package, not the
files on the disk.''
If '''pkgadd''' finds that a specific file should not be upgraded, it will install it under %fn%/var/lib/pkg/rejected/%%.
Files in this directory are never added to the package database. The user is then free to examine, use and/or remove that
file manually. Another option is to use '''rejmerge'''. For each rejected file found in %fn%/var/lib/pkg/rejected/%%,
rejmerge will display the difference between the installed version and the rejected version. The user can then choose to
keep the installed version, upgrade to the rejected version or perform a merge of the two. Example (using the above
%fn%/etc/pkgadd.conf%%):
$ pkgadd -u bash#5.0.18-1.pkg.tar.gz
pkgadd: rejecting etc/profile, keeping existing version
$ ls /var/lib/pkg/rejected/
etc/
$ ls /var/lib/pkg/rejected/etc/
profile
!!! Removing a Package
Removing a package is done by using '''pkgrm'''. This utility requires one argument, the name of the package you want to
remove. Example:
$ pkgrm bash
->%lfloat%http://crux.nu/doc/images/warning.png
'''Warning'''[[]]
->''This will remove all files owned by the package, no questions asked. Think twice before doing it and make sure that
you did not misspell the package name since that could remove something completely different (e.g. think about what could
happen if you misspelled %fn%glib%% as %fn%glibc%%).''
!!! Querying the Package Database
Querying the package database is done using '''pkginfo'''. This utility has a few options to answer different queries.
||cellpadding="3" rules="all" frame="box"
||! Option ||! Description
||-i, --installed ||List installed packages and their version.
||-l, --list package|file ||List files owned by the specified package or contained in file
||-o, --owner pattern ||List owner(s) of file(s) matching pattern.
Examples:
[@
$ pkginfo -i
audiofile 0.2.3-1
autoconf 2.52-1
automake 1.5-1
...>
xmms 1.2.7-1
zip 2.3-1
zlib 1.1.4-1
@]
[@
$ pkginfo -l bash
bin/
bin/bash
bin/sh
etc/
etc/profile
usr/
usr/man/
usr/man/man1/
usr/man/man1/bash.1.gz
usr/man/man1/sh.1.gz
@]
[@
$ pkginfo -l grep#2.5-1.pkg.tar.gz
usr/
usr/bin/
usr/bin/egrep
usr/bin/fgrep
usr/bin/grep
usr/man/
usr/man/man1/
usr/man/man1/egrep.1.gz
usr/man/man1/fgrep.1.gz
usr/man/man1/grep.1.gz
@]
[@
$ pkginfo -o bin/ls
e2fsprogs usr/bin/lsattr
fileutils bin/ls
modutils sbin/lsmod
@]
!! Package management frontend: prt-get
In its current form '''pkgutils''' does not have a concept of dependency handling. To address this a frontend utility called '''prt-get''' was created. It supports dependency handling (with the caveat mentioned below) as well as some overlap with '''pkgutils''' features and has been an official part of CRUX for some time.
!!! Functionality
Some examples of prt-get's functionality and use are as follows:
Listing installed ports:
[@
$ prt-get listinst
acl
attr
autoconf
[...]
$ prt-get listinst -v
acl 2.2.53-3
attr 2.4.48-1
autoconf 2.69-2
[...]
@]
Querying information about a port:
[@
$ prt-get info acl
Name: acl
Path: /usr/ports/core
Version: 2.2.53
Release: 3
Description: Access Control Lists library
URL: http://savannah.nongnu.org/projects/acl
Maintainer: CRUX System Team, core-ports at crux dot nu
Dependencies: attr
@]
Searching for ports by name:
[@
$ prt-get search glibc
glibc
glibc-32
$ prt-get search --regex '(ba|z)sh$'
bash
zsh
@]
Searching for ports by installed file:
[@
$ prt-get fsearch gconv
Found in /usr/ports/core/glibc:
/usr/lib/gconv/
Found in /usr/ports/core/glibc-32:
/usr/lib32/gconv/
@]
Searching for ports by words in their descriptions:
[@
$ prt-get dsearch shell
dash
dialog
dsh
[...]
zsh
@]
Viewing dependency lists:
[@
$ prt-get depends bash
-- dependencies ([i] = installed)
[i] ncurses
[i] readline
[i] bash
$ prt-get quickdep bash
ncurses readline bash
$ prt-get deptree bash
-- dependencies ([i] = installed, '-->' = seen before)
[i] bash
[i] readline
[i] ncurses
@]
Installing ports:
[@
$ prt-get install xterm
@]
->%lfloat%http://crux.nu/doc/images/note.png
'''Note'''[[]]
->''The 'install' command does NOT process dependencies and it is usually recommended to use 'depinst' (next) instead!''
[@
$ prt-get depinst xterm
@]
Viewing and updating outdated ports (generally after 'ports -u'):
Listing installed ports which are out of date:
[@
$prt-get diff
Differences between installed packages and ports tree:
Port Installed Available in the ports tree
bind 9.16.7-1 9.16.8-1
@]
Updating an individual port:
[@
$ prt-get update xterm
@]
Updating all installed ports:
[@
$ prt-get sysup
@]
->%lfloat%http://crux.nu/doc/images/note.png
'''Note'''[[]]
->''Currently 'update' and 'sysup' do not process new dependencies introduced after the initial installation of a port. To
show such additions to the dependency lists of installed ports, you can chain together several invocations of
%fn%prt-get%% with one invocation of %fn%awk%% as follows.''
[@
$ prt-get isinst $(prt-get quickdep $(prt-get quickdiff)) | awk '/not installed/ {print $2}'
@]
!!! Configuration
!!!! /etc/prt-get.conf
'''prt-get''''s main configuration file, '/etc/prt-get.conf', contains options that can be used to change prt-get's behavior. Notably in this file the following options can be configured:
%fn%prtdir%% - This option can occur multiple times and specifies a directory with a 'collection' of ports prt-get should check in its operation. By default the 'core', 'opt', and 'xorg' collections are enabled. The 'compat-32' and 'contrib' collections are disabled by default, see sections "Enabling the 'contrib' collection" and "Enabling the 'compat-32' collection".
%fn%logfile%% - This option configures a file for prt-get to log its operation if desired.
%fn%runscripts%% - This option configures prt-get to run pre-/post-install scripts if they exist in ports being installed or updated. It is recommended that this be enabled as in many cases if a pre- or post-install script exists in a port, it is required to be run for proper operation.
!!!! /etc/prt-get.aliases
'''prt-get''' has a concept of aliases which can be used in a fashion similar to the concept of 'provides' in some other
Linux distributions. This file is %fn%/etc/prt-get.aliases%% and contains lines in the following format:
[@
postfix: sendmail
exim: sendmail
qmail: sendmail
masqmail: sendmail
@]
The above set of aliases indicates that %fn%postfix%%, %fn%exim%%, %fn%qmail%%, and %fn%masqmail%% are all considered
sufficient to satisfy a dependency on '%fn%sendmail%%' in a port.
Sometimes the port maintainer will list among the required dependencies a lightweight library, to save on compilation time
for the majority of users. If you already have the more powerful library installed, you can use %fn%prt-get.aliases%% to
avoid automatic installation of the lightweight alternative. For example, on a system with %fn%mozjs91%% already built,
you would not want %fn%prt-get depinst polkit%% to build fn%duktape%% as well. This can be accomplished with the following
line in %fn%prt-get.aliases%%:
[@
mozjs91: duktape
@]
Another case where this might be useful would be that of replacing a slow-compiling source port with a precompiled binary
port in order to save time. For example the following would indicate that '%fn%rust-bin%%' is considered sufficient to
satisfy a dependency on '%fn%rust%%' in a port:
[@
rust-bin: rust
@]
->%lfloat%http://crux.nu/doc/images/note.png
'''Note'''[[]]
->''prt-get's alias function does NOT automatically replace ports during an install or depinst operation. If a port
depends on '%fn%rust%%' and neither '%fn%rust-bin%%' or '%fn%rust%%' are installed, prt-get will install '%fn%rust%%' as
listed in the port's dependencies. If '%fn%rust-bin%%' is installed before the depending port's install or depinst
operation, on the other hand, '''prt-get''' will consider the dependency satisfied.''
This is NOT an exhaustive list of all of '''prt-get''''s commands, features, and configuration options, merely a starting
point. More information can be found in the [[https://crux.nu/doc/prt-get%20-%20User%20Manual.html | manual]] and
[[https://crux.nu/doc/prt-get%20-%20Quick%20start.html | quick start]] documentation.
!! Creating Packages
Creating a package is done using '''pkgmk'''. This utility uses a file called %fn%Pkgfile%%, which contains information
about the package (such as name, version, etc) and the commands that should be executed in order to compile the package in
question.
To be more specific, the %fn%Pkgfile%% file is actually a '''bash(1)''' script, which defines a number of variables (name,
version, release and source) and a function (build). Below is an example of what a %fn%Pkgfile%% file might look like. The
example shows how to package the '''grep(1) utility'''. Some comments are inserted for explanation.
[@
# Specify the name of the package.
name=grep
# Specify the version of the package.
version=2.4.2
# Specify the package release.
release=1
# The source(s) used to build this package.
source=(ftp://ftp.ibiblio.org/pub/gnu/$name/$name-$version.tar.gz)
# The build() function below will be called by pkgmk when
# the listed source files have been unpacked.
build() {
# The first thing we do is to cd into the source directory.
cd $name-$version
# Run the configure script with desired arguments.
# In this case we want to put grep under /usr/bin and
# disable national language support.
./configure --prefix=/usr --disable-nls
# Compile.
make
# Install the files, BUT do not install it under /usr, instead
# we redirect all the files to $PKG/usr by setting the DESTDIR
# variable. The $PKG variable points to a temporary directory
# which will later be made into a tar.gz-file. Note that the
# DESTDIR variable is not used by all Makefiles, some use prefix
# and others use ROOT, etc. You have to inspect the Makefile in
# question to find out. Some Makefiles do not support redirection
# at all. In those cases you will have to create a patch for it.
make DESTDIR=$PKG install
# Remove unwanted files, in this case the info-pages.
rm -rf $PKG/usr/info
}
@]
In reality you do not include all those comments, thus the real %fn%Pkgfile%% for '''grep(1)''' looks like this:
[@
# Description: GNU grep, egrep and fgrep
# URL: http://www.gnu.org/software/grep/grep.html
# Maintainer: Per Lidén, per at fukt dot bth dot se
name=grep
version=2.4.2
release=1
source=(ftp://ftp.ibiblio.org/pub/gnu/$name/$name-$version.tar.gz)
build() {
cd $name-$version
./configure --prefix=/usr --disable-nls
make
make DESTDIR=$PKG install
rm -rf $PKG/usr/info
}
@]
->%lfloat%http://crux.nu/doc/images/note.png
'''Note'''[[]]
->''The build() function in the example above is just an example of how '''grep''' is built. The contents of the function
can differ significantly if the program is built in some other way, e.g. does not use '''autoconf'''.''
When the build() function has been executed, the %fn%$PKG%% directory will be made into a package named
%fn%''<name>#<version>-<release>''.pkg.tar.gz%%.
Before the package creation is completed, '''pkgmk''' will check the content of the package against the %fn%.footprint%%
file. If this file does not exist, it will be created and the test will be skipped.
The %fn%.footprint%% file will contain a list of all files that should be in the package if the build was successful or a
list of all the files that were installed in %fn%$PKG%% (if the %fn%.footprint%% did not already exist). If there is a
mismatch the test will fail and an error message will be printed. You should not write the %fn%.footprint%% file by hand.
Instead, when a package has been upgraded and you need to update the contents of the %fn%.footprint%% file you simply do
'''pkgmk -uf'''. This test ensures that a rebuild of the package turned out as expected.
If the package built without errors it's time to install it by using '''pkgadd''' and try it out. I highly recommend
looking at the %fn%Pkgfile%% in another package(s), since looking at examples is a great way to learn.
->%lfloat%http://crux.nu/doc/images/note.png
'''Note'''[[]]
->''Please see the [[https://crux.nu/Main/PortGuidelines | PortGuidelines]] for additional information''.''
!! Adjusting/Configuring the Package Build Process
Many settings pertaining to the package build process can be adjusted by editing the '''pkgmk(8)''' configuration file
'''/etc/pkgmk.conf'''. Some of these configurable settings include:
* CFLAGS, CXXFLAGS - these settings control optimization and architecture options for package compiles. '''It is best NOT
to change these unless you absolutely know what you're doing!'''
* PKGMK_SOURCE_MIRRORS - this setting defines locations from which pkgmk will attempt to fetch source archives. If this
array only contains mirrors administered by the CRUX team, building a port from your personal collection might result in
''404 Not Found'' errors until all the mirrors are exhausted, and then the source defined in the Pkgfile will be tried.
* PKGMK_SOURCE_DIR - this setting defines where pkgmk will store (if downloading) and use source archives when building
* PKGMK_PACKAGE_DIR - this setting defines where pkgmk will create package files once the build process is complete
* PKGMK_WORK_DIR - this setting defines a work area pkgmk will use to build the package
Here are some examples:
[@
PKGMK_SOURCE_MIRRORS=(http://fileserver.intranet/crux/sources/)
@]
This setting instructs pkgmk to attempt to fetch all source archives from [=http://fileserver.intranet/crux/sources/=] before falling back to the source URL specified in the Pkgfile. Multiple URLS can be separated by spaces.
[@
PKGMK_SOURCE_DIR="/usr/ports/srcfiles"
@]
This example instructs pkgmk to store and find source archives in /usr/ports/srcfiles. An example benefit of this setup
would be the ability to store /usr/ports/srcfiles on an NFS server on your local network for use by multiple crux
installations. (PKGMK_PACKAGE_DIR can be set and used the same way. But if NFS is too challenging to set up on your local
network and you find it easier to configure an http server instead, %fn%pkg-get%% from the %fn%opt%% collection gives you
an alternative mechanism for sharing built packages.)
[@
PKGMK_WORK_DIR="/usr/ports/work/$name"
@]
This example instructs pkgmk to use /usr/ports/work/$name as a work area for building the specified package. Building the
'''grep''' package would result in the work area being '''/usr/ports/work/grep'''. An alternative would be to use a tmpfs
as your work directory.
There are a few more settings which can be found in the pkgmk.conf man page.
!! Package Guidelines
!!! General
* The name of a package should always be lowercase (e.g. name=eterm and not name=Eterm). In case the package is added to
the CRUX ports system the exact same name should be use for the name of the directory in the ports structure, i.e.
%fn%/usr/ports/???/eterm%%.
* Do not combine several separately distributed programs/libraries into one package. Make several packages instead.
* The build function should never touch anything outside the work directory, and ideally should not rely on having
an internet connection (say, to download sources not listed in the %fn%source%% array). While '''pkgmk''' does not
currently recognize git urls in the %fn%source%% array, efforts are underway to add this feature, thereby removing the
temptation to write a build function that reaches out to the internet for the latest git source tree.
-> The motivation for a policy of separating 'download' from 'build' is that a user with intermittent internet access
should be able to run @@pkgmk -do@@ in the directory of every outdated package, and then go offline to finish the sysup
operation. Language-specific toolchains, like those embraced by rust and python (cargo and pip, respectively), are making
this policy more difficult to enforce. You are free to forego CRUX pkgutils and let the ecosystems of the ''N'' different
languages manage their respective software in separate subdirectories (like python's %fn%~/.local/share/virtualenv%% or
rust's %fn%~/.cargo%%), at the expense of having to learn '''N+1''' administration suites rather than just the 1 suite of
CRUX pkgutils. Every language-specific project that appears in the official repositories represents a hard-won effort by
the CRUX development team to sustain the historic method of software deployment, in the face of software development
trends all heading away from this model.
!!! Directories
* In general packages should install files in these directories. Exceptions are of course allowed if there is a good reason. But try to follow the following directory structure as close as possible.
>>margin-left=40px
||cellpadding="3" rules="all" frame="box"
||! Directory ||! Description
||%fn%/usr/bin/%% ||User command/application binaries
||%fn%/usr/sbin/%% ||System binaries (e.g. daemons)
||%fn%/usr/lib/%% ||Libraries
||%fn%/usr/include/%% ||Header files
||%fn%/usr/lib/<prog>/%% ||Plug-ins, addons, etc
||%fn%/usr/share/man/%% ||Man pages
||%fn%/usr/share/<prog>/%% ||Data files
||%fn%/usr/etc/<prog>/%% ||Configuration files
||%fn%/etc/%% ||Configuration files for system software (daemons, etc)
>>
* %fn%/opt%% directory is reserved for manually compiled/installed applications. Packages should never place anything there.
* %fn%/usr/libexec/%% is not used in CRUX, thus packages should never install anything there. Use %fn%/usr/lib/<prog>/%% instead.
!!! Remove Junk Files
* Packages should not contain &#8220;junk files&#8221;. This includes info pages and other online documentation, man pages excluded (e.g. %fn%usr/doc/*%%, %fn%README%%, %fn%*.info%%, %fn%*.html%%, etc).
* Files related to NLS (national language support), always use '''--disable-nls''' when available.
* Useless or obsolete binaries (e.g. %fn%/usr/games/banner%% and %fn%/sbin/mkfs.minix%%).
!!! Pkgfile
* Do not add new variables to the %fn%Pkgfile%%. Only in very few cases does this actually improve the readability or the quality of the package. Further, the only variables that are guranteed to work with future versions of '''pkgmk''' are @@name@@, @@version@@, @@release@@, and @@source@@. Other names could be in conflict with internal variables in '''pkgmk'''.
* Use the @@$name@@ and @@$version@@ variables to make the package easier to update/maintain. For example, [=source=(http://xyz.org/$name-$version.tar.gz)=] is better than [=source=(http://xyz.org/myprog-1.0.3.tar.gz)=] since the URL will automatically updated when you modify the @@$version@@ variable.
* Remember that @@source@@ is an array, i.e. always do @@source=(...)@@ and not @@source=...@@
* Another array that '''pkgmk''' will make use of, if defined, is @@renames@@ (introduced in CRUX 3.7). This array lets
you save the downloaded source tarballs with a more descriptive filename, to avoid filename collisions when using a shared
directory for downloads. See the %fn%Pkgfile%% man page for more details.
!!!! Pkgfile header
Provide a header including the following fields:
||cellpadding="3" rules="all" frame="box"
||!Name ||!Meaning ||
||Description||A short description of the package; keep it factual||
||Maintainer||Your full name and e-mail address, obfuscated if you want||
||Packager||The original packager's full name and e-mail address||
||URL||A webpage with more information on this software package||
||Depends on||A list of dependencies, separated either by spaces or commas||
@@Depends on@@ can be omitted if there are no dependencies; @@Packager@@ can be omitted if the maintainer and packager are the same person.
'''Example header'''
[@
# Description: Terminal based IRC client for UNIX systems
# URL: http://www.irssi.org/
# Maintainer: Jukka Heino, jukka at karsikkopuu dot net
# Packager: Daniel K. Gebhart, dkg at con-fuse dot org
# Depends on: glib
@]

195
crux-wiki/Handbook3-7-Ports Normal file
View File

@ -0,0 +1,195 @@
! The Ports System
!! Introduction
!!! What is a Port?
A port is a directory containing the files needed for building a package using '''pkgmk'''. This means that this directory at least has the files %fn%Pkgfile%% (which is the package build description) and %fn%.footprint%% (which is used for regression testing and contains a list of files this package is expected to contain once it is built). Further, a port directory can contain patches and/or other files needed for building the package. It is important to understand that the actual source code for the package is not necessarily present in port directory. Instead the %fn%Pkgfile%% contains an URL which points to a location where the source can be downloaded.
The use of the word ''port'' in this context is borrowed from the BSD world, where a ''port'' refers to a program that has been ported to a system or platform. The word can sometimes be a bit misleading since most programs require no actual porting to run on CRUX (or on Linux in general).
!!! What is the Ports System?
The term ''Ports System'' refers to a remote repository containing ports and a client program capable of downloading ports from that repository. The administrator of
a CRUX system runs the '''ports(8)''' bash script to download ports from the remote repository and place them in %fn%/usr/ports/%%. The '''ports''' script uses
rsync(1) or httpup(1) or git(1) to do the actual downloading/synchronization.
!!! Port collections
CRUX ports are organized in so-called 'collections'. There are three different layers of ports:
!!!! The official collections 'core', 'opt', 'xorg' and 'compat-32'
%fn%core%%, %fn%opt%%, %fn%xorg%% and %fn%compat-32%% are the four primary collections of CRUX. They're maintained by the CRUX development team which ensures that they're consistent and working well together. The first three are enabled by default. The %fn%compat-32%% collection is disabled by default and contains 32-bit compatibility ports.
!!!! The user contributed collection 'contrib'
The %fn%contrib%% collection is a collection which is provided by experienced port maintainers: some are part of the CRUX development team, while others are regular users. Its goal is to reduce the number of duplicate ports provided in the individual collections. If you're a seasoned port maintainer, you might even want to join the contrib collection.
As those ports are not provided officially by the CRUX development team, this collection is disabled by default.
!!!! The individual collections from CRUX users
Using [[HttpUp]] or git, every user can publish his or her own ports easily; the only requirement for that is some
webspace to upload the ports. Maintaining an HttpUp repository of ports, which you've tested and gotten successfully
running, is a simple way to contribute back to the CRUX community.
!! Using the Ports System
!!! Synchronizing Your Local Ports Structure
When CRUX is installed for the first time the local ports structure (%fn%/usr/ports/%%) is empty. To bring your local ports structure up to date you use the '''ports''' utility with the '''-u''' option. Example:
$ ports -u
The '''-u''' option means update, and tells '''ports''' to contact the ports repository and download new and updated ports. The output from this execution is something like this:
Updating file list from crux.nu::ports/crux-3.7/core/
Updating collection ports/crux-3.7/core/
...
Updating file list from crux.nu::ports/crux-3.7/opt/
Updating collection ports/crux-3.7/opt/
...
Updating file list from crux.nu::ports/crux-3.7/xorg/
Updating collection ports/crux-3.7/xorg/
...
Finished successfully
The output reveals which files are downloaded, updated and deleted.
!!! Listing Local Ports
When the local ports structure has been updated the directory %fn%/usr/ports/%% will contain two package categories, %fn%core%% and %fn%opt%%. Under each of these directories you will find ports. You can simply browse around in the directory structure to find out which ports are available.
$ cd /usr/ports/core/
$ ls
You can also use '''ports''' with the '''-l''' option to list all local ports. Example:
$ ports -l
core/autoconf
core/automake
core/bash
core/bc
core/bin86
core/bindutils
core/binutils
...
If you are looking for a specific package, it might be easier to use this approach (e.g. @@ports -l | grep sendmail@@) to find out if the package is available and if so in which category it is located.
!!! Listing Version Differences
To find out if the ports structure carries ports that are different (likely newer) compared to the versions currently installed you can use the option '''-d'''. If version differences are found, the output from the above command could look something like this:
$ ports -d
Collection Name Port Installed
core glibc 2.3.6-3 2.3.6-2
opt gtk 2.8.12-1 2.8.11-1
If no version differences were found, i.e. the system is in sync with the ports structure, the output will simply be:
$ ports -d
No differences found
!!! Building and Installing Packages
Once you have found a port that you want to build and install you simply go into the desired port directory and use '''pkgmk''' to build it. Example:
$ cd /usr/ports/core/gawk
$ pkgmk -d
The '''-d''' option means download missing source files and tells '''pkgmk''' to download the source(s) specified in the Pkgfile (in case the source is already downloaded this option is ignored). When the download is completed the package will be built. If the package was built successfully you can use '''pkgadd''' to install or upgrade it. Example:
$ pkgadd gawk#3.1.5-3.pkg.tar.gz
To make life a bit easier these two steps can be made into one by using the options '''-i''' (for install) or '''-u''' (for upgrade). Example:
$ pkgmk -d -i
or
$ pkgmk -d -u
This will download, build and then install/upgrade the package. Note that the package will only be installed/upgraded if the build is successful.
!!! Enabling the 'contrib' collection
As previously mentioned, the 'contrib' collection contains useful ports of experienced port maintainers. Since they are
not provided by the CRUX development team, you should be slightly more critical with respect to quality and security.
However, members with write permissions for 'contrib' are usually well-known and active in the CRUX community.
To enable the 'contrib' collection so that @@ports -u@@ will bring it up to date, just rename its rsync file.
[@
$ cd /etc/ports
$ mv contrib.rsync.inactive contrib.rsync
@]
You will probably also want to let %fn%prt-get%% know about the newly-enabled 'contrib' tree. This can be done by editing
%fn%/etc/prt-get.conf%% and uncommenting the line @@prtdir /usr/ports/contrib@@ (i.e. remove the hashmark in the beginning of
the line. After that, it should look like this:
[@
###
### prt-get conf
###
# note: the order matters: the package found first is used
prtdir /usr/ports/core
prtdir /usr/ports/opt
# the following line enables the user maintained contrib collection
prtdir /usr/ports/contrib
@]
Now, run @@ports -u@@ and you're ready to use the ports from %fn%contrib%%.
!!! Enabling the 'compat-32' collection
The 'compat-32' collection contains compatibility ports needed for 32-bit support (32-bit applications running on a 64-bit multilib system.)
To enable it for %fn%ports%%, do
[@
$ cd /etc/ports
$ mv compat-32.rsync.inactive compat-32.rsync
@]
The 'compat-32' collection is enabled in the same way as the 'contrib' collection (described previously) for usage with %fn%prt-get%%.
As with 'contrib', run @@ports -u@@ and you're ready to use the ports from %fn%compat-32%%.
!!! Additional tools
!!!! Building ports as unprivileged user
Building packages requires root privileges in order to create files with the correct owner and group. This is a security
concern because a malicious or badly designed port can run arbitrary commands when its Pkgfile is sourced by the shell.
The '''fakeroot''' command provides a way to build ports as normal user. Particularly when you build packages from user
contributed repositories you are advised to use '''fakeroot''':
[@
$ fakeroot pkgmk -d
@]
* You can also make '''prt-get''' use '''fakeroot''', by modifying the line in %fn%prt-get.conf%% that contains
@@makecommand@@. This line would allow a non-root user running @@prt-get@@ to create packages with no footprint mismatches
(wrong owner/group), but the installation of these packages (and the running of pre-/post-install scripts) needs additional
privileges.
* Additional lines in %fn%prt-get.conf%%, defining @@addcommand@@ and @@runscriptcommand@@ with '''sudo''' or
'''doas''', is one way to let @@prt-get@@ work properly for a non-root user.
* Another possibility is to write a '''sudo''' or '''doas''' configuration that grants permission to run @@prt-get@@
itself, and then as a non-root user you would always run @@sudo prt-get@@ rather than @@prt-get@@ directly.
* Read the man pages for %fn%prt-get.conf%% and %fn%sudo/doas%% to learn how these pieces fit together, and choose whichever
option you like best. To give extra scrutiny to ports you find outside the official repositories, it helps to
restrict yourself to low-level commands @@pkgmk@@ and @@pkgadd@@ rather than the wrapper program @@prt-get@@. This
practice forces you to be in the directory of the unofficial port, where the %fn%Pkgfile%% source array and build function
are more likely to receive your careful attention.
!!!! Useful scripts
Regarding package and ports management there are many tasks which can be done in several steps with the CRUX standard
tools introduced above. The %fn%opt%% repository contains a port called [[PrtUtils|prt-utils]] with many such scripts.
Other combinations of low-level tools, using UNIX pipes, command substitution, and text processing utilities, can be found
in the bug tracker, the mailing list, and IRC logs. Efforts are underway to bring this diaspora of institutional knowledge
into a central place, such as the EXAMPLES section of the most relevant man page.