crux-wiki: redirect visitors to the sandbox namespace on crux.nu

This commit is contained in:
John McQuah 2022-08-26 15:27:59 -04:00
parent 058a8807af
commit 519d085a4b
7 changed files with 378 additions and 1073 deletions

View File

@ -1,162 +0,0 @@
# This outline of a CRUX installation for full-disk encryption is provided
# based on the experience of one user. There are many other possible ways
# to set up an encrypted disk. At every stage of the installation, you have a
# number of different options. It is easy to get overwhelmed by all the decisions
# involved.
#
# Extra packages: lz4 if you choose this compression mode for the kernel,
# dracut and lvm2 to access the logical volumes when booting
parted -s -a optimal /dev/sda \
mklabel gpt \
mkpart primary fat32 0% 500MiB \
name 1 esp \
set 1 esp on \
mkpart primary 500MiB 4GiB \
name 2 swap \
mkpart primary 4GiB 100% \
name 3 ENCRYPTED
mkfs.vfat /dev/sda1
cryptsetup -q -c aes-cbc-essiv:sha256 -d /dev/urandom create swap /dev/sda2
mkswap -f /dev/mapper/swap
swapon /dev/mapper/swap
##### For AES Encryption
##### cryptsetup luksFormat --type luks2 -c aes-cbc-essiv:sha256 /dev/sda3
cryptsetup luksFormat --type luks2 -c serpent-xts-plain64 -s 512 /dev/sda3
##### The device node is now set up, but it needs a mapping to be usable as disk space
##### Replace 'ENCRYPTED' with whatever name you want
cryptsetup luksOpen /dev/sda3 ENCRYPTED
pvcreate /dev/mapper/ENCRYPTED
##### On the newly-mapped physical volume, create the desired logical volumes
vgcreate ENCRYPTED /dev/mapper/ENCRYPTED
lvcreate -L 30G ENCRYPTED -n root
lvcreate -L 4G ENCRYPTED -n var
lvcreate -L 50G ENCRYPTED -n usr
lvcreate -L 3G ENCRYPTED -n opt
lvcreate -l 100%FREE ENCRYPTED -n home
##### Format each logical volume with the desired filesystem
##### ("flash-friendly" FS works well with the encryption overhead, but btrfs or ext4 are also possible)
mkfs.f2fs /dev/mapper/ENCRYPTED-root
mkfs.f2fs /dev/mapper/ENCRYPTED-var
mkfs.f2fs /dev/mapper/ENCRYPTED-usr
mkfs.f2fs /dev/mapper/ENCRYPTED-opt
mkfs.f2fs /dev/mapper/ENCRYPTED-home
##### Mount the root FS where the CRUX installer expects it
mount /dev/mapper/ENCRYPTED-root /mnt
##### Do the same for any partitions that will be written to during CRUX installation
mkdir /mnt/{var,usr,opt,home,boot}
mount /dev/mapper/ENCRYPTED-var /mnt/var
mount /dev/mapper/ENCRYPTED-usr /mnt/usr
mount /dev/mapper/ENCRYPTED-opt /mnt/opt
mount /dev/mapper/ENCRYPTED-home /mnt/home
mount /dev/sda1 /mnt/boot
setup # --> Install these extra packages (cryptsetup lvm2 syslinux dracut lz4)
setup-chroot
passwd
localedef -i en_US -f UTF-8 en_US.UTF-8
cat <<EOF > /etc/fstab
/dev/mapper/ENCRYPTED-root / f2fs defaults 0 0
#/dev/mapper/swap swap swap defaults 0 0
/dev/sda1 /boot vfat defaults 0 0
/dev/mapper/ENCRYPTED-var /var f2fs defaults 0 0
/dev/mapper/ENCRYPTED-usr /usr f2fs defaults 0 0
/dev/mapper/ENCRYPTED-opt /opt f2fs defaults 0 0
/dev/mapper/ENCRYPTED-home /home f2fs defaults 0 0
EOF
##### Now write a custom initscript to create an encrypted swap partition with
##### randomized cipher on each boot
cat <<EOF > /etc/rc.d/swap
#!/bin/sh
PROG="/usr/sbin/cryptsetup"
SWAP="swap"
CIPH="aes-cbc-essiv:sha256"
PART="/dev/sda2"
case $1 in
start)
if [ -e /dev/mapper/swap ] ; then
if swapon --show | grep -qs partition ; then
exit 0
else
swapon /dev/mapper/${SWAP}
exit 0
fi
else
${PROG} -q -c ${CIPH} -d /dev/urandom create ${SWAP} ${PART}
mkswap -f /dev/mapper/${SWAP}
swapon /dev/mapper/${SWAP}
exit 0
fi
;;
stop)
swapoff -a
sleep 1
${PROG} close /dev/mapper/${SWAP}
;;
status)
swapon --show
;;
*)
echo "usage: $0 [start|stop|status]"
;;
esac
EOF
##### Make the above initscript executable, and add it to the SERVICES array
chmod +x /etc/rc.d/swap
vi /etc/rc.conf
SERVICES=(swap lo net crond)
##### Continue configuring the network and building the kernel
vi /etc/rc.d/net
vi /etc/dracut.conf.d/modules.conf
add_dracutmodules+=" crypt lvm "
cd /usr/src/linux-5.15.55
make menuconfig
make all && make modules_install
##### Install the kernel, syslinux bootloader, and initramfs
mkdir -p /boot/efi/BOOT
cp arch/x86/boot/bzImage /boot/efi/BOOT/vmlinuz-5.15.55
cp System.map /boot/efi/BOOT/System.map-5.15.55
cp .config /boot/efi/BOOT/config-5.15.55
dracut --kver 5.15.55 /boot/initramfs-5.15.55.img
cp /usr/share/syslinux/efi64/syslinux.efi /boot/efi/BOOT/bootx64.efi
cp /usr/share/syslinux/efi64/ldlinux.e64 /boot/efi/BOOT
vi /boot/efi/BOOT/syslinux.cfg
PROMPT 1
TIMEOUT 10
DEFAULT CRUX
LABEL CRUX
LINUX vmlinuz-5.15.55
APPEND root=/dev/mapper/ENCRYPTED-root rw rd.auto=1
INITRD initramfs-5.15.55.img
##### Reboot, and enjoy your new CRUX installation!

View File

@ -14,8 +14,7 @@ The following runlevels are used in CRUX (defined in %fn%/etc/inittab%%).
!!! Layout
The initialization scripts used in CRUX follow the BSD-style (as opposed to the
SysV-style) and have the following 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
@ -28,8 +27,7 @@ SysV-style) and have the following layout.
||%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.
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
@ -40,22 +38,17 @@ The following configuration variables are found in %fn%/etc/rc.conf%%.
(: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/%%.
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/%%.
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/%%.
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
@ -70,35 +63,23 @@ 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'''.
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 '''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:
!! [[#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 '''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
!! 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:
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
@ -150,9 +131,8 @@ 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:
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
@ -215,98 +195,61 @@ nameserver your DNS server>
# End of file
@]
To associate with a WPA2-protected wireless network, you should first create a
configuration file for %fn%wpa_supplicant%% to use, then launch wpa_supplicant
on that interface.
To associate with a WPA2-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 MYPASS > /etc/wpa_supplicant-wlan0.conf
$ wpa_supplicant -i wlan0 -c /etc/wpa_supplicant-wlan0.conf
-> Replace '''MYNETWORK''' with the ssid of your network, '''MYPASS''' with its
passphrase, and '''wlan0''' with the name of your actual network interface. Run
@@ip link@@ to see the list of all available interfaces.
-> Replace %fn%MYNETWORK%% with the ssid of your network, %fn%MYPASS%% with its passphrase, and %fn%wlan0%% with the name of your actual network interface. Run @@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 @@dhcpcd wlan0@@ to request an address from
the DHCP server.
If the %fn%wpa_supplicant%% output indicates a successful authentication, you can background the process and run @@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 '''wpa_supplicant'''
manage all your network interfaces. Another option is to let the '''net'''
startup script call '''wpa_supplicant''' as needed, by copying into
%fn%/lib/dhcpcd/dhcpcd-hooks/%% the example file
%fn%/usr/share/dhcpcd/hooks/10-wpa_supplicant%%.
The '''wpa_supplicant''' package provides two startup scripts in %fn%/etc/rc.d%%. You might choose to put %fn%wlan%% in the SERVICES array of %fn%/etc/rc.conf%% (replacing %fn%net%%), which will let '''wpa_supplicant''' manage all your network interfaces. Another option is to let the %fn%net%% startup script call '''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.
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).
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 @@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.
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 @@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.
A new default in CRUX 3.7 is that the value of PATH, for shells that rely on
%fn%/etc/profile%% to set this variable, will be the same regardless of UID.
This change allows non-root users easy access to any administrative command
without having to type its full path (provided they use '''bash''' as their
shell and are given the appropriate '''doas/sudo''' permissions). Users are
always free to choose a different shell and manage PATH themselves, but the
default behaviour is now less likely to cause confusion.
A new default in CRUX 3.7 is that the value of PATH, for shells that rely on %fn%/etc/profile%% to set this variable, will be the same regardless of UID. This change allows non-root users easy access to any administrative command without having to type its full path (provided they use '''bash''' as their shell and are given the appropriate '''doas/sudo''' permissions). Users are always free to choose a different shell and manage PATH themselves, but the default behaviour is now less likely to cause confusion.
The core packages '''linux-pam''' and '''dumb_runtime_dir''', and the contrib
package '''pam_xdg''', provide a variety of modules that can be loaded upon
logging in. 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). Some typical situations that
The core packages '''linux-pam''' and '''dumb_runtime_dir''', and the contrib package '''pam_xdg''', provide a variety of modules that can be loaded upon logging in. 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). Some typical situations that
can be handled cleanly with PAM modules are listed in the table below.
||cellpadding="3" rules="all" frame="box"
||! file in /etc/pam.d ||! Typical usage
||%fn%pam_dumb_runtime_dir.so%% || create an XDG_RUNTIME_DIR for applications that conform to the freedesktop.org specification
||%fn%pam_env.so%% || export some common environment variables, no matter what login shell the user has chosen
||%fn%pam_xdg.so%% || export the XDG environment variables defined in the freedesktop.org specification
||%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 after successful authentication
(:table cellpadding="3" rules="all" frame="box":)
(:cell align=center:)'''file in /etc/pam.d'''
(:cell align=center:)'''Typical usage'''
(:cellnr:)%fn%pam_dumb_runtime_dir.so%%
(:cell:)
create an XDG_RUNTIME_DIR for applications that conform to the freedesktop.org specification
(:cellnr:)%fn%pam_env.so%%
(:cell:)
export some common environment variables, no matter what login shell the user has chosen
(:cellnr:)%fn%pam_xdg.so%%
(:cell:)
export the XDG environment variables defined in the freedesktop.org specification
(:cellnr:)%fn%pam_limits.so%%
(:cell:)
increase the allowed number of opened files, to ensure proper operation of some games
(:cellnr:)%fn%pam_xauth.so%%
(:cell:)
grant another user access to the X display of the logged-in user, so that programs invoked with ''su'' can work properly
(:cellnr:)%fn%pam_mount.so%%
(:cell:)
automatically mount a LUKS-encrypted home partition after successful authentication
(:tableend:)
->%lfloat% http://crux.nu/doc/images/note.png
'''Note'''[[]]
-> The existence of a writable XDG_RUNTIME_DIR is required for proper operation of
many desktop applications. A ''clean'' CRUX 3.7 installation will place a line
in %fn%/etc/pam.d/common-session%% that loads the module fn%pam_dumb_runtime_dir.so%%
to satisfy this requirement. An ''upgrade'' to CRUX 3.7 might not do so,
depending on your UPGRADE directives in %%fn%/etc/pkgadd.conf%%. But any
configuration that allows desktop applications to run smoothly on CRUX 3.6 will
probably continue working after an upgrade to 3.7.
-> While '''pam_dumb_runtime_dir''' has a simple design and restricts itself to
the creation of the runtime dir, the 'contrib' collection offers an alternative,
'''pam_xdg''', which exports all the environment variables defined in the
freedesktop.org specification. You should choose ONE of these two options and
edit %fn%/etc/pam.d/common-session%% accordingly.
'''Note'''[[<<]]
-> The existence of a writable XDG_RUNTIME_DIR is required for proper operation of many desktop applications. A ''clean'' CRUX 3.7 installation will place a line in %fn%/etc/pam.d/common-session%% that loads the module %fn%pam_dumb_runtime_dir.so%% to satisfy this requirement. An ''upgrade'' to CRUX 3.7 might not do so, depending on your UPGRADE directives in %fn%/etc/pkgadd.conf%%. But any configuration that allows desktop applications to run smoothly on CRUX 3.6 will probably continue working after an upgrade to 3.7.
-> While '''pam_dumb_runtime_dir''' has a simple design and restricts itself to the creation of the runtime dir, the 'contrib' collection offers an alternative, '''pam_xdg''', which exports all the environment variables defined in the freedesktop.org specification. You should choose ONE of these two options and edit %fn%/etc/pam.d/common-session%% accordingly.
If you find yourself in one of the other situations in the table above, read the man
page for the corresponding PAM module to learn how to accomplish the desired
configuration.
If you find yourself in one of the other situations in the table above, read the man page for the corresponding PAM module to learn how to accomplish the desired configuration.
!! 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
unpack the newer source tree 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.
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 unpack the newer source tree 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.

View File

@ -1,162 +1,83 @@
! 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.
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 2GB system memory is required to install CRUX from a DVD or
removable flash drive. It is possible to perform a custom chroot installation
with a smaller amount of RAM.
A minimum of 2GB system memory is required to install CRUX from a DVD or removable flash drive. It is possible to perform a custom chroot installation with a smaller amount 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.
The kernel used during installation, i.e. when booting from the CRUX ISO image (El Torito), is compiled with support for most disk controllers. If your hard disk is not recognized after booting from the ISO image (i.e., the output of @@lsblk@@ only shows the CRUX media), you might find a solution in the [[https://crux.nu/Wiki/HomePage | CRUX wiki]], the [[https://lists.crux.nu/pipermail/crux/ | mailing lists]], or the [[https://crux.nu/Main/Bugs | bug tracker]]. You could also ask for help on the [[https://crux.nu/Main/IrcChannels |CRUX IRC channels]]. For example, the owner of a low-power machine that uses a board soldered memory card as its main disk was able to install CRUX successfully after building an ISO with kernel customized to enable @@CONFIG_X86_INTEL_LPSS@@.
!! [[#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.
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).
* 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.
* 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]].''
'''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 5G root partition (CRUX will use
about 500MB-1GB, depending on whether you create separate partition for %fn%/usr%%,
and other decisions you make in the setup process).
The amount of disk space required depends on how many packages are selected to install. It is recommended to have at least a 5G root partition (CRUX will use about 500MB-1GB, depending on whether you create separate partition for %fn%/usr%%, and other decisions you make in the setup process).
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]].
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).
'''Note: MBR'''[[]]
->If your BIOS does not support UEFI boot mode (or you have disabled it in
favor of legacy MBR mode), then you do not need to create a separate small
partition for EFI loaders or kernel images. One large partition for %fn%%/%%
is enough in such cases, and GRUB should be able to find a Linux kernel
saved in the subdirectory %fn%/boot%%. But selecting SYSLINUX for your
bootloader will require you to flag as bootable whichever partition contains
%fn%syslinux.cfg%%. See [[#syslinux-install | "SYSLINUX installation" ]] in
the Appendix for details.
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.
'''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).
->%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.''
'''Note: MBR'''[[<<]]
->If your BIOS does not support UEFI boot mode (or you have disabled it in favor of legacy MBR mode), then you do not need to create a separate small partition for EFI loaders or kernel images. One large partition for %fn%/%% is enough in such cases, and GRUB should be able to find a Linux kernel saved in the subdirectory %fn%/boot%%. But selecting SYSLINUX for your bootloader will require you to flag as bootable whichever partition contains %fn%syslinux.cfg%%. See [[#BootLoader-Setup | Installing a Bootloader ]] below for more details.
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 that any BIOS Virus Protection option is DISABLED as this option
may prevent '''fdisk''' from writing new partitions correctly.''
'''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:
* 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%%.
* 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: 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.''
->%lfloat% http://crux.nu/doc/images/note.png
'''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 @@&#8220;0 error(s)&#8221;@@.
After the packages have finished installing, the '''setup''' script will display an installation log. Make sure the last line in the log says @@&#8220;0 error(s)&#8221;@@.
If you missed or forgot to install certain packages, you can just mount the CRUX
installation medium and use '''pkgadd''' to install them.
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 &#8220;chroot&#8221; into your new CRUX
installation.
* Now it's time to compile your kernel and do basic system configuration. The kernel compilation requires that you &#8220;chroot&#8221; 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.''
'''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
@ -168,54 +89,32 @@ installation.
$ 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:''
[[#fstabNotes]]
* 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%%.
* 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.55%%, configure and compile a new kernel.
* 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.
[[#KernelBuildingNotes]]
->%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:
'''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.55/.config%% which is a good starting point for a
custom kernel, because all needed options, like CONFIG_DEVTMPFS, are
enabled.
'''Note'''[[<<]]
->The setup program installs a configuration file %fn%/usr/src/linux-5.15.55/.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.55
$ make menuconfig
@ -225,113 +124,71 @@ enabled.
$ cp System.map /boot
->%lfloat%http://crux.nu/doc/images/note.png
'''Note'''[[]]
->The location %fn%/boot%% is the default path that GRUB will
search for kernel images. If you use SYSLINUX or the kernel itself as
your bootloader, then modify the @@cp@@ commands to copy the kernel into a
more appropriate location, e.g., the subdirectory %fn%EFI/BOOT%% under the
mountpoint of the EFI system partition.
'''Note'''[[<<]]
->The location %fn%/boot%% is the default path that GRUB will search for kernel images. If you use the kernel's EFI stub as your bootloader, then modify the @@cp@@ commands to copy the kernel into a more appropriate location, e.g., the subdirectory %fn%EFI/BOOT%% under the mountpoint of the EFI system partition. The SYSLINUX bootloader on UEFI systems will also require a different location for the saved kernel; see [[#SYSLINUX-uefi|SYSLINUX, in UEFI boot mode]] for the proper @@cp@@ commands.
->%lfloat%http://crux.nu/doc/images/note.png
'''Note'''[[]]
->A user-contributed example of a modular kernel configuration has been
provided, if you want to boot a kernel that can tell you the exact set of
modules needed for your particular hardware, or if you find it too daunting to
navigate through the interface of the @@make menuconfig@@ step. You can find
this file, %fn%config-5.15.55-modular%%, under %fn%/crux/kernel/contrib%% on
the installation media.
'''Note'''[[<<]]
->A user-contributed example of a modular kernel configuration has been provided, if you want to boot a kernel that can tell you the exact set of modules needed for your particular hardware, or if you find it too daunting to navigate through the interface of the @@make menuconfig@@ step. You can find this file, %fn%config-5.15.55-modular%%, under %fn%/crux/kernel/contrib%% on the installation media.
[[#BootLoader-Setup]] !!! Installing a Bootloader
[[#BootLoader-Setup]]
!!! Installing a Bootloader
-->Unless you compiled your kernel to provide an EFI stub '''and have UEFI
boot mode enabled in your BIOS''', you will want to install a bootloader on
your hard disk. Simple instructions are provided below for four distinct
combinations of bootloader and BIOS setting. You are advised to choose one
of the following options based on how your BIOS is configured and on how
much you value "do-it-yourself" config files. The EFI stub option is
presented in the [[#EFI-stub-install|Appendix]], if you find it
simpler to modify EFI variables rather than configuration files.
''Unless you compiled your kernel to provide an EFI stub and have UEFI boot mode enabled in your BIOS, you will want to install a bootloader on your hard disk.'' Simple instructions are provided below for four distinct combinations of bootloader and BIOS setting. You are advised to choose ''one'' of the following options based on how your BIOS is configured and on how much you value &#8220;do-it-yourself&#8221; config files. The EFI stub option is presented in the [[#EFI-stub-install|Appendix]], if you find it simpler to modify EFI variables rather than configuration files.
* GRUB, in UEFI boot mode:
** Install grub2 into the EFI system partition 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.
** Run @@grub-mkconfig > /boot/grub/grub.cfg@@, or
[[#grubcfg-manually|create a config file by hand]].
* GRUB, in legacy (non-UEFI) boot mode:
** 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.
** Run @@grub-mkconfig > /boot/grub/grub.cfg@@, or
[[#grubcfg-manually|create a config file by hand]].
** @@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/]].
* SYSLINUX, in UEFI boot mode:
** Copy the bootloader code from %fn%/usr/share/syslinux%% to the mounted
EFI system partition, specifically the subdirectory %fn%EFI/BOOT%%, which
most UEFI implementations will search by default. (In this example the ESP
is assumed to be mounted at %fn%/boot/efi%%)
->%lfloat%http://crux.nu/doc/images/note.png
'''Note'''[[<<]]
->LILO is no longer maintained in the official ports collections. If you were using LILO to boot CRUX 3.6 or earlier, you are advised to replace the boot sector with GRUB or SYSLINUX when upgrading to CRUX 3.7.
->%lfloat%http://crux.nu/doc/images/note.png
'''Note'''[[<<]]
->Dual-booting with another operating system is not covered in this handbook. There are more extensive resources for such installations on the [[https://wiki.syslinux.org|SYSLINUX wiki]] or the [[https://www.gnu.org/software/grub/manual/grub|GRUB manual]].
!!!! GRUB, in UEFI boot mode:
* Install grub2 into the EFI system partition using a command like '''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.
* Run '''grub-mkconfig > /boot/grub/grub.cfg''', or [[#grubcfg-manually|create a config file by hand]].
!!!! GRUB, in legacy (non-UEFI) boot mode:
* 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.
*Run '''grub-mkconfig > /boot/grub/grub.cfg''', or [[#grubcfg-manually|create a config file by hand]].
* @@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/]].
!!!! SYSLINUX, in UEFI boot mode:
* Copy the bootloader code from %fn%/usr/share/syslinux%% to the mounted EFI system partition, specifically the subdirectory %fn%EFI/BOOT%%, which most UEFI implementations will search by default. (In this example the ESP is assumed to be mounted at %fn%/boot/efi%%)
[@
$ mkdir -p /boot/efi/EFI/BOOT
$ cd /boot/efi/EFI/BOOT
$ cp /usr/src/linux-5.15.55/arch/x86/boot/bzImage vmlinuz-5.15.55
$ cp /usr/share/syslinux/efi64/ldlinux.e64 .
$ cp /usr/share/syslinux/efi64/syslinux.efi BOOTX64.EFI
$ cat <<EOF > syslinux.cfg
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
# End of config file
EOF
@]
** Saving a copy of %fn%syslinux.efi%% to the more generic name
%fn%BOOTX64.EFI%% helps avoid the extra step of customizing boot entries
with @@efibootmgr@@.
** If you choose a different mountpoint for the EFI partition, adjust the
@@mkdir@@ and @@cd@@ commands accordingly (UEFI itself is completely
agnostic about mountpoints specified in %fn%/etc/fstab).
** Proceed to [[#syslinux-cfg|write a syslinux configuration file]], keeping
in mind where you saved the kernel image.
* SYSLINUX, in legacy (non-UEFI) boot mode:
** Create a syslinux directory on a vfat or ext2/3/4-formatted partition,
and populate it with the kernel and bootloader. '''Assuming that %fn%/boot%% is
on a partition marked bootable''', you can do:
* Saving a copy of %fn%syslinux.efi%% to the more generic name %fn%BOOTX64.EFI%% helps avoid the extra step of customizing boot entries with @@efibootmgr@@.
* If you choose a different mountpoint for the EFI partition, adjust the @@mkdir@@ and @@cd@@ commands accordingly (UEFI itself is completely agnostic about mountpoints specified in %fn%/etc/fstab).
* SYSLINUX interprets relative paths to the kernel in reference to the %fn%syslinux.cfg%% file, but cannot cross filesystem boundaries to find the kernel. Therefore the @@cp@@ command from the [[#KernelBuildingNotes | kernel building step]] is not applicable when SYSLINUX is installed on the EFI mountpoint %fn%/boot/efi%%, and a different target directory appears in the @@cp@@ commands above.
!!!! SYSLINUX, in legacy (non-UEFI) boot mode:
* Create a syslinux directory on a vfat or ext2/3/4-formatted partition, and populate it with the kernel and bootloader. ''Assuming that %fn%/boot%% is on a partition marked bootable'', you can do:
[@
$ mkdir /boot/syslinux
$ cd /boot/syslinux
$ cp /usr/share/syslinux/ldlinux.c32 .
$ cp /usr/src/linux-5.15.55/arch/x86/boot/bzImage ../vmlinuz-5.15.55
$ extlinux --install /boot/syslinux
@]
** Replacing %fn%/boot/syslinux%% in the above commands with
%fn%/boot/efi/EFI/BOOT%% will make it easy to toggle between legacy and UEFI
boot modes.
** Next, overwrite the contents of the master boot record (MBR) with the
binary blob appropriate for your partition type (%fn%gptmbr.bin%% in the
case of GPT/GUID partitioning, or %fn%mbr.bin%% in the case of DOS
partitioning).
[@
$ PTYPE=$(fdisk -l /dev/sda | grep "^Disklabel type" | cut -d " " -f3)
$ [ "$PTYPE" = "gpt" ] && BINBLOB=gptmbr.bin || BINBLOB=mbr.bin
$ dd bs=440 count=1 conv=notrunc if=/usr/share/syslinux/$BINBLOB of=/dev/sda
@]
** Proceed to write a syslinux configuration file, keeping in mind where you
saved the kernel image.
[[#syslinux-cfg]] Template for a SYSLINUX configuration file
If you select SYSLINUX as your bootloader, you need to tell it where
to find your kernel and the root filesystem.
SYSLINUX interprets relative paths to the kernel in reference to the
%fn%syslinux.cfg%% file. In the template below, suppose @@extlinux@@
assigned %fn%/boot/syslinux%% as the preferred location for
%fn%syslinux.cfg%%, and a copy of the kernel was saved in the parent
directory as %fn%/boot/vmlinuz-5.15.55%%. The relative path therefore
begins with %fn%../% .
[@
cat <<EOF > syslinux.cfg
$ [ -e ../vmlinuz-5.15.55 ] || cp /usr/src/linux-5.15.55/arch/x86/boot/bzImage ../vmlinuz-5.15.55
$ cat <<EOF > syslinux.cfg
DEFAULT CRUX-3.7
PROMPT 1
TIMEOUT 10
@ -340,73 +197,54 @@ LABEL CRUX-3.7
SAY "Now booting into CRUX"
KERNEL ../vmlinuz-5.15.55
APPEND root=/dev/sda2 rw quiet
# End of config file
EOF
@]
* Replacing %fn%/boot/syslinux%% in the above commands with %fn%/boot/efi/EFI/BOOT%% will make it easy to toggle between legacy and UEFI boot modes.
* SYSLINUX interprets relative paths to the kernel in reference to the %fn%syslinux.cfg%% file, although it cannot cross filesystem boundaries to find the kernel. On a legacy system with no dedicated EFI partition, the @@cp@@ command from the [[#KernelBuildingNotes | kernel building step]] should put the kernel in a reachable path, hence the @@cp@@ command above does not need to run if the kernel was already copied to the expected place.
* Finally, overwrite the contents of the master boot record (MBR) with the binary blob appropriate for your partition type (%fn%gptmbr.bin%% in the case of GPT/GUID partitioning, or %fn%mbr.bin%% in the case of DOS partitioning).
[@
$ PTYPE=$(fdisk -l /dev/sda | grep "^Disklabel type" | cut -d " " -f3)
$ [ "$PTYPE" = "gpt" ] && BINBLOB=gptmbr.bin || BINBLOB=mbr.bin
$ dd bs=440 count=1 conv=notrunc if=/usr/share/syslinux/$BINBLOB of=/dev/sda
@]
-->More information about UEFI and other boot loader/manager options can be
found in the CRUX wiki at [[https://crux.nu/Wiki/UEFI]].
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.
Remove the CRUX installation media from your computer and reboot from harddisk.
!! Upgrading From DVD-ROM or removable flash drive
!! Upgrading 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.
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.
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).
* 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:
* 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.
* 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.
** Upgrading packages that were linked to soft dependencies ''outside core and opt'' will replace them with packages that were only linked to dependencies in core and opt. You will have to rebuild such packages if you want to retain the functionality of your existing CRUX system.
** On the other hand, if it's been a while since you refreshed the ports tree on your existing CRUX system and rebuilt the outdated packages, an upgrade of all packages will save you from trouble (e.g. if some library introduced breaking changes).
->%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"]]).''
'''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/%% (see the section [[#UpgradingaPackage | "Upgrading a Package"]] for advice on how to resolve such file conflicts).''
When the '''setup''' script has upgraded the selected packages an upgrade log
will be displayed. Make sure the last line in the log says @@&#8220;0
error(s)&#8221;@@. 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''').
When the '''setup''' script has upgraded the selected packages an upgrade log will be displayed. Make sure the last line in the log says @@&#8220;0 error(s)&#8221;@@. 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 &#8220;chroot&#8221; into your CRUX installation and compile
a fresh kernel from the latest source tree.
* 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 &#8220;chroot&#8221; 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.''
'''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
@ -417,19 +255,8 @@ a fresh kernel from the latest source tree.
(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.
* Generate locales for your system. See the section [[#LocaleGeneration| Generating locales]] for more information.
* Go to %fn%/usr/src/linux-5.15.x%%, configure and compile a new kernel. See the [[#KernelBuildingNotes| kernel building step]] for some reminders of how that is done.
* Adjust %fn%/etc/fstab%% to reflect any changes made to your partition scheme since your earlier installation of CRUX. In particular, %fn%/var/run%% should not appear as a mountpoint, since this is now a symlink to %fn%/run%% starting with CRUX 3.7. See the [[#fstabNotes|notes about fstab]] in the previous section for other general recommendations.
* Go to %fn%/usr/src/linux-5.15.x%%, configure and compile a new kernel. See the
[[#KernelBuildingNotes| kernel building notes]] from the "Install" section
for some reminders of how that is done.
* Adjust %fn%/etc/fstab%% to reflect any changes made to your partition
scheme since your earlier installation of CRUX. In particular,
%fn%/var/run%% should not appear as a mountpoint, since this is now a
symlink to %fn%/run%% starting with CRUX 3.7. See the notes about
%fn%fstab%% in the [[#InstallingFromCD-ROM| "Installing"]] section for other
general recommendations.
Finish the upgrade by [[#BootLoader-Setup | installing a bootloader]], and
then you should be able to login to your upgraded CRUX system after
rebooting.
Finish the upgrade by [[#BootLoader-Setup | Installing a Bootloader]], and then you should be able to login to your upgraded CRUX system after rebooting.

View File

@ -1,71 +1,35 @@
! Preface
!Preface
[[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.
[[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.
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 the CRUX development team strives to introduce new features as soon as
they reach stable status, such innovations are carefully screened to ensure
that they work in CRUX without drastic changes to the upstream sources or to
the rest of the CRUX system.
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/share/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. Lastly, while the CRUX development team strives to introduce new features as soon as they reach stable status, such innovations are carefully screened to ensure that they work in CRUX without drastic changes to the upstream sources or to the rest of the CRUX system.
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 appreciates the challenge of navigating third-party source trees
and figuring out what it takes to compile them.
* A somewhat experienced Linux user who wants a clean and solid Linux distribution as the foundation of your installation.
* Someone who appreciates the challenge of navigating third-party source trees and figuring out what it takes to compile them.
* Someone who has the patience to rebuild large packages on a regular basis.
* Someone who enjoys exploring and discussing with other enthusiasts the intricacies
of putting together an operating system.
* Someone who enjoys exploring and discussing with other enthusiasts the intricacies of putting together an 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.''
''If you are using CRUX, we highly recommend 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.
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]].
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.
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.

View File

@ -1,84 +1,46 @@
!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).
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%%.
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.
'''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'''.
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.
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:
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 existing 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:
When installing a package the package manager will ensure that no existing 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)
->No such error message is issued for already-existing directories, since
the package database allows a directory to be associated with more than one
package. However, the owner/group and permissions of an existing directory will
not be changed to match those of the requested package.
->No such error message is issued for already-existing directories, since the package database allows a directory to be associated with more than one package. However, the owner/group and permissions of an existing directory will not be changed to match those of the requested package.
To force the installation when conflicting files are reported, you can use the
option '''-f''' (or '''--force'''). Example:
To force the installation when conflicting files are reported, 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.
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.
->%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.''
'''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.
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
@ -86,30 +48,13 @@ 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.
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 5.0.18-1 with version 5.0.16-1 (or even with version 5.0.18-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%%.
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 &#8220;keep list&#8221; (in addition to the &#8220;non-install list&#8221; 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.
%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:
[@
@ -125,51 +70,60 @@ Example:
# 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.
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.''
'''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%%):
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
[@
$ pkgadd -u ports#1.6-3.pkg.tar.gz
pkgadd: rejecting etc/ports/compat-32.pub, keeping existing version
pkgadd: rejecting etc/ports/compat-32.rsync.inactive, keeping existing version
pkgadd: rejecting etc/ports/contrib.pub, keeping existing version
pkgadd: rejecting etc/ports/contrib.rsync.inactive, keeping existing version
pkgadd: rejecting etc/ports/core.pub, keeping existing version
pkgadd: rejecting etc/ports/core.rsync, keeping existing version
pkgadd: rejecting etc/ports/opt.pub, keeping existing version
pkgadd: rejecting etc/ports/opt.rsync, keeping existing version
pkgadd: rejecting etc/ports/xorg.pub, keeping existing version
pkgadd: rejecting etc/ports/xorg.rsync, keeping existing version
$ tree -L 3 /var/lib/pkg/rejected/
/var/lib/pkg/rejected
etc
ports
compat-32.pub
compat-32.rsync.inactive
contrib.pub
contrib.rsync.inactive
core.pub
core.rsync
drivers
opt.pub
opt.rsync
xorg.pub
xorg.rsync
@]
If this %fn%pkgadd.conf%% had been in place during an upgrade from CRUX 3.6 to 3.7, and you neglected to check the contents of %fn%/var/lib/pkg/rejected/%% (either manually or by running @@rejmerge@@), then '''ports -u''' would synchronize your ports tree with the older branch! Hence you should always pay attention to warnings and errors reported by @@pkgadd@@.
!!! 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:
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%%).''
'''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.
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
@ -181,13 +135,14 @@ Examples:
[@
$ pkginfo -i
audiofile 0.2.3-1
autoconf 2.52-1
automake 1.5-1
acl 2.3.1-1
alsa-lib 1.2.7.2-1
alsa-utils 1.2.7-1
...>
xmms 1.2.7-1
zip 2.3-1
zlib 1.1.4-1
yasm 1.3.0-2
zip 3.0-2
zlib 1.2.12-1
zstd 1.5.2-1
@]
[@
@ -205,7 +160,7 @@ Examples:
@]
[@
$ pkginfo -l grep#2.5-1.pkg.tar.gz
$ pkginfo -l grep#3.7-1.pkg.tar.gz
usr/
usr/bin/
usr/bin/egrep
@ -225,13 +180,9 @@ Examples:
modutils sbin/lsmod
@]
!! Package management frontend: prt-get
!! 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.
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
@ -242,14 +193,14 @@ Listing installed ports:
[@
$ prt-get listinst
acl
attr
autoconf
alsa-lib
alsa-utils
[...]
$ prt-get listinst -v
acl 2.2.53-3
attr 2.4.48-1
autoconf 2.69-2
acl 2.3.1-1
alsa-lib 1.2.7.2-1
alsa-utils 1.2.7-1
[...]
@]
@ -259,8 +210,8 @@ Querying information about a port:
$ prt-get info acl
Name: acl
Path: /usr/ports/core
Version: 2.2.53
Release: 3
Version: 2.3.1
Release: 1
Description: Access Control Lists library
URL: http://savannah.nongnu.org/projects/acl
Maintainer: CRUX System Team, core-ports at crux dot nu
@ -327,9 +278,8 @@ $ 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!''
'''Note'''[[<<]]
->''The 'install' command does NOT process dependencies and it is usually recommended to use 'depinst' (next) instead!''
[@
$ prt-get depinst xterm
@ -344,12 +294,12 @@ Differences between installed packages and ports tree:
Port Installed Available in the ports tree
bind 9.16.7-1 9.16.8-1
inkscape 1.2-1 1.2.1-1
@]
Updating an individual port:
[@
$ prt-get update xterm
$ prt-get update inkscape
@]
Updating all installed ports:
@ -358,42 +308,27 @@ $ 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.''
'''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
!!! Configuring prt-get
!!!! /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:
'''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%prtdir%% - This option can occur multiple times and specifies a directory with a 'collection' that prt-get should search for ports. 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%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.
%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:
'''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
@ -402,57 +337,34 @@ 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.
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%%:
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
@]
->%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%duktape%%' and neither
'%fn%duktape%%' nor '%fn%mozjs91%%' are installed, prt-get will install
'%fn%duktape%%' as listed in the port's dependencies. If '%fn%mozjs91%%' was
installed before the depending port's install or depinst operation, on the other
hand, '''prt-get''' will consider the dependency satisfied.''
'''Note'''[[<<]]
->''prt-get's alias function does NOT automatically replace ports during an install or depinst operation. If a port depends on '%fn%duktape%%' and neither '%fn%duktape%%' nor '%fn%mozjs91%%' are installed, prt-get will install '%fn%duktape%%' as listed in the port's dependencies. If '%fn%mozjs91%%' was 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.
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.
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.
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
version=3.7
# Specify the package release.
release=1
@ -489,16 +401,15 @@ build() {
}
@]
In reality you do not include all those comments, thus the real %fn%Pkgfile%%
for '''grep(1)''' looks like this:
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
# Maintainer: Per Lid&#65533;n, per at fukt dot bth dot se
name=grep
version=2.4.2
version=3.7
release=1
source=(ftp://ftp.ibiblio.org/pub/gnu/$name/$name-$version.tar.gz)
@ -512,59 +423,26 @@ build() {
@]
->%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'''.''
'''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 contents 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.
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 contents 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.
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 [[#PackageGuidelines | Package Guidelines]] for
additional recommendations regarding Pkgfile variables (name, version, release,
build) and the footprint.''
'''Note'''[[<<]]
->''Please see the [[#PackageGuidelines | Package Guidelines]] for additional recommendations regarding Pkgfile variables (name, version, release, build) and the footprint.''
!! 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
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:
@ -572,73 +450,35 @@ 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.
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.)
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.
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.
[[#PackageGuidelines]] !! Package Guidelines
[[#PackageGuidelines]]
!! 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.
-> Apart from ensuring a consistent mechanism to verify the integrity of sources
(@@signify@@), the policy of separating 'download' from 'build' allows a
user with intermittent internet access 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 team to sustain
the historic method of software deployment, in the face of software development
trends all heading away from this model.
* 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.
--> Apart from ensuring a consistent mechanism to verify the integrity of sources (@@signify@@), the policy of separating 'download' from 'build' allows a user with intermittent internet access 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 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