diff --git a/crux-wiki/Handbook3-7-Configuration b/crux-wiki/Handbook3-7-Configuration index e5866b0..79a7a73 100644 --- a/crux-wiki/Handbook3-7-Configuration +++ b/crux-wiki/Handbook3-7-Configuration @@ -14,7 +14,8 @@ 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 @@ -27,7 +28,8 @@ The initialization scripts used in CRUX follow the BSD-style (as opposed to the ||%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 @@ -38,17 +40,22 @@ 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 @@ -63,16 +70,24 @@ 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 %fn%pkgmk%%, the locale C.UTF-8 is generated as part of the CRUX installation. Any -other desired locales must be created by the administrator. A typical setup for swedish users would use the following -commands, so replace @@sv_SE*@@ with the locale you want: +Starting with CRUX 2.5, glibc does not contain all possible locales anymore, +thus you'll have to generate the locales you need/use. To ensure proper +operation of %fn%pkgmk%%, the locale C.UTF-8 is generated as part of the CRUX +installation. Any other desired locales must be created by the administrator. A +typical setup for swedish users would use the following commands, so replace +@@sv_SE*@@ with the locale you want: + # localedef -i sv_SE -f ISO-8859-1 sv_SE # localedef -i sv_SE -f ISO-8859-1 sv_SE.ISO-8859-1 # localedef -i sv_SE -f UTF-8 sv_SE.UTF-8 @@ -80,7 +95,10 @@ commands, so replace @@sv_SE*@@ with the locale you want: !!! 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 @@ -132,7 +150,9 @@ 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 @@ -195,54 +215,75 @@ nameserver your DNS server> # End of file @] -To associate with a password-protected wireless network, you should first create a configuration file for -%fn%wpa_supplicant%% to use, then launch wpa_supplicant on that interface. +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 MYPASSWORD > /etc/wpa_supplicant-wlan0.conf $ wpa_supplicant -i wlan0 -c /etc/wpa_supplicant-wlan0.conf --> Replace '''wlan0''' with the name of your actual network interface. Run %fn%ip link%% to see the list of all available -interfaces. +-> Replace '''wlan0''' with the name of your actual network interface. Run +%fn%ip link%% to see the list of all available interfaces. -If the %fn%wpa_supplicant%% output indicates a successful authentication, you can background the process and run -%fn%dhcpcd wlan0%% to request an address from the DHCP server. +If the %fn%wpa_supplicant%% output indicates a successful authentication, you +can background the process and run %fn%dhcpcd wlan0%% to request an address from +the DHCP server. -The '''wpa_supplicant''' package provides two startup scripts in %fn%/etc/rc.d%%. You might choose to put '''wlan''' in the -SERVICES array of %fn%/etc/rc.conf%% (replacing '''net'''), which will let %fn%wpa_supplicant%% manage all your -network interfaces. Another option is to let the '''net''' startup script call %fn%wpa_supplicant%% as needed, by copying -into %fn%/lib/dhcpcd/dhcpcd-hooks/%% the example file %fn%/usr/share/dhcpcd/hooks/10-wpa_supplicant%%. +The '''wpa_supplicant''' package provides two startup scripts in +%fn%/etc/rc.d%%. You might choose to put '''wlan''' in the SERVICES array of +%fn%/etc/rc.conf%% (replacing '''net'''), which will let %fn%wpa_supplicant%% +manage all your network interfaces. Another option is to let the '''net''' +startup script call %fn%wpa_supplicant%% as needed, by copying into +%fn%/lib/dhcpcd/dhcpcd-hooks/%% the example file +%fn%/usr/share/dhcpcd/hooks/10-wpa_supplicant%%. !! Passwords and User Environment -CRUX uses SHA512 passwords by default. To change the password encryption method set the ENCRYPT_METHOD variable in %fn%/etc/login.defs%% to DES, MD5 or SHA256. +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 %fn%useradd -m%% will not automatically populate the home directory with a basic shell -startup file, as happens on other Linux distributions whose %fn%/etc/skel/%% contains their idea of an initial home -directory. No such decisions are imposed on CRUX administrators, who get to work with the upstream tools in their -unmodified state. +Also configurable in %fn%/etc/login.defs%% are the settings that govern how +@@useradd(8)@@ behaves when you create a new non-root user, such as CREATE_HOME +and USERGROUPS_ENAB. First-time CRUX administrators might be surprised to learn +that creating a new user via %fn%useradd -m%% will not automatically populate +the home directory with a basic shell startup file, as happens on other Linux +distributions whose %fn%/etc/skel/%% contains their idea of an initial home +directory. No such decisions are imposed on CRUX administrators, who get to work +with the upstream tools in their unmodified state. -The core packages '''linux-pam''' and '''dumb_runtime_dir''' provide a number of modules that can be loaded upon -successful login. The files in %fn%/etc/pam.d%% govern the association between the type of login (eg., tty, SSH, su, X -Display Manager) and the modules that get loaded (eg., pam_env, pam_exec, pam_limits). Read the manpage for any PAM module -of interest, to learn how it might be configured for your needs. Some typical situations that can be solved with PAM -modules are listed in the table below. +The core packages '''linux-pam''' and '''dumb_runtime_dir''', and the contrib +package '''pam_xdg''', provide a number 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_env.so%% || export some mandatory environment variables, no matter what login shell the user has chosen +||%fn%pam_env.so%% || export some common environment variables, no matter what login shell the user has chosen ||%fn%pam_limits.so%% || increase the allowed number of opened files, to ensure proper operation of some games ||%fn%pam_xauth.so%% || grant another user access to the X display of the logged-in user, so that programs invoked with ''su'' can work properly -||%fn%pam_mount.so%% || automatically mount a LUKS-encrypted home partition +||%fn%pam_mount.so%% || automatically mount a LUKS-encrypted home partition after successful authentication ||%fn%pam_dumb_runtime_dir.so%% || create an XDG_RUNTIME_DIR for applications that conform to the freedesktop.org specification +||%fn%pam_xdg.so%% || export the XDG environment variables defined in the freedesktop.org specification + +If you find yourself in one of the 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 place it -somewhere else). This will not make the package database inconsistent (since it's not installed with '''pkgadd''') nor -will it affect the kernel headers found in %fn%/usr/include/linux%% and %fn%/usr/include/asm%% since these are not -symlinks to the kernel source, but instead contain copies of the headers. +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. diff --git a/crux-wiki/Handbook3-7-Intro b/crux-wiki/Handbook3-7-Intro index bbaf921..63ff986 100644 --- a/crux-wiki/Handbook3-7-Intro +++ b/crux-wiki/Handbook3-7-Intro @@ -1,43 +1,71 @@ -[[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 CRUX strives to use new features as they become available, you will never have to deal with a frenzy of innovation that leaves you with an unrecognizable system. A CRUX user from the early years could abandon the distribution for two decades, then install the latest release and feel right at home. +There are many Linux distributions out there these days, so what makes CRUX such +an appealing choice to its users? The choice of distribution is a matter of +taste, really. Here are a few hints about the tastes and goals of the people +behind CRUX. CRUX is made with simplicity in mind from beginning to end. Making +it easy to create new and update old packages is essential; updating a package +in CRUX is often just a matter of typing %fn%sudo prt-get update $MYPKG%%. +The usage of ports helps keep your packages up to date; not the latest +bleeding-edge-alpha version, but the latest stable version. Other features +include creating packages optimized for your processor, eg. by compiling with +-march=x86-64, and avoiding cluttering the filesystem with files you'll never +use, eg. /usr/doc/*, etc. If you need more information about a specific program, +other than information found in the man-page, Google usually knows all about it. +Although CRUX strives to use new features as they become available, you will +never have to deal with a frenzy of innovation that leaves you with an +unrecognizable system. A CRUX user from the early years could abandon the +distribution for two decades, then install the latest release and feel right at +home. In short, CRUX might suit you very well if you are: -* A somewhat experienced Linux user who wants a clean and solid Linux distribution as the foundation of your installation. + +* A somewhat experienced Linux user who wants a clean and solid Linux +distribution as the foundation of your installation. + * Someone who does not hesitate to download and compile programs from the source. -* Someone who values consistency and stability in the essential components of the operating system. + +* Someone who values consistency and stability in the essential components of +the operating system. %lfloat% http://crux.nu/doc/images/note.png '''Note'''[[]] -''If you are using CRUX, we highly recommend to subscribing to our low-volume [[MailingLists | mailing list]] because security updates and updates that need user action are announced there.'' - - +''If you are using CRUX, we highly recommend to subscribing to our low-volume +[[MailingLists | mailing list]] because security updates and updates that need +user action are announced there.'' !!License !!!Packages -Since CRUX is a Linux distribution, it contains software written by a lot of different people. Each software package comes with its own license, chosen by its author(s). To find out how a particular package is licensed, have a look at its source code. +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 +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. diff --git a/crux-wiki/Handbook3-7-Package b/crux-wiki/Handbook3-7-Package index bf1b9db..cbcff06 100644 --- a/crux-wiki/Handbook3-7-Package +++ b/crux-wiki/Handbook3-7-Package @@ -1,51 +1,80 @@ !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%''#-''.pkg.tar.gz%%, where %fn%%% is the name of the program, %fn%%% is the version -number of the program, and %fn%%% 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%''#-''.pkg.tar.gz%%, where %fn%%% is the name +of the program, %fn%%% is the version number of the program, and +%fn%%% 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 previously installed files are overwritten. If conflicts are found, an error message will be printed and '''pkgadd''' will abort without installing the package. The error message will contain the names of the conflicting files. Example: +When installing a package the package manager will ensure that no previously +installed files are overwritten. If conflicts are found, an error message will +be printed and '''pkgadd''' will abort without installing the package. The error +message will contain the names of the conflicting files. Example: $ pkgadd bash#5.0.18-1.pkg.tar.gz bin/sh usr/man/man1/sh.1.gz pkgadd error: listed file(s) already installed (use -f to ignore and overwrite) -To force the installation and overwrite the conflicting files, you can use the option '''-f''' (or '''--force'''). Example: +To force the installation and overwrite the conflicting files, you can use the +option '''-f''' (or '''--force'''). Example: $ pkgadd -f bash#5.0.18-1.pkg.tar.gz -The package system allows a file to be owned by exactly one package. When forcing an installation the ownership of the conflicting files will be transferred to the package that is currently being installed. Directories can however be owned by more then one package. +The package system allows a file to be owned by exactly one package. When +forcing an installation the ownership of the conflicting files will be +transferred to the package that is currently being installed. Directories can +however be owned by more then one package. ->%lfloat%http://crux.nu/doc/images/warning.png '''Warning'''[[]] -->''It is often not a good idea to force the installation unless you really know what you are doing. If a package conflicts with already installed files it could be a sign that the package is broken and installs unexpected files. Use this option with extreme care, preferably not at all.'' +->''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 @@ -53,20 +82,31 @@ 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 “upgrade” 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 “upgrade” version 2.05-1 with version 2.04-1 +(or even with version 2.05-1 itself). The installed package will be replaced +with the specified package. -Upgrading a package is not simply a wrapper for '''pkgrm''' followed by '''pkgadd''', because you usually want to preserve -your customizations of the config and log files that are owned by the already-installed package. Therefore, @@pkgadd -u@@ -conducts some upgrade-specific checks of the filesystem and the package database to construct what is called a '''keep -list''', in addition to the '''non-install list''' (which is initialized for every '''pkgadd''' transaction). The -construction of both lists is governed by the file %fn%/etc/pkgadd.conf%%. +Upgrading a package is not simply a wrapper for '''pkgrm''' followed by +'''pkgadd''', because you usually want to preserve your customizations of the +config and log files that are owned by the already-installed package. Therefore, +@@pkgadd -u@@ conducts some upgrade-specific checks of the filesystem and the +package database to construct what is called a '''keep list''' (in addition to +the '''non-install list''' which is initialized for every '''pkgadd''' +transaction). The construction of both lists is governed by the file +%fn%/etc/pkgadd.conf%%. -%fn%/etc/pkgadd.conf%% can contain rules describing how '''pkgadd''' should behave when installing or -upgrading any package. A rule is built out of three fragments; ''event'', ''pattern'' and ''action''. The event names the -kind of operation (INSTALL or UPGRADE) to which this rule will be applied. The ''pattern'' is a filename pattern expressed -as a regular expression and the action applicable to the INSTALL or UPGRADE ''event'' is YES or NO. More than one rule of -the same event type is allowed, in which case the first rule will have the lowest priority and the last rule will have the -highest priority. Example: +%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: [@ # @@ -81,21 +121,25 @@ highest priority. 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 “/” since you are referring to the files in the package, not the -files on the disk.'' +->''A pattern should never contain an initial “/” 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 @@ -106,20 +150,22 @@ keep the installed version, upgrade to the rejected version or perform a merge o !!! 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%%).'' +->''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 @@ -177,7 +223,11 @@ Examples: !! 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 @@ -274,7 +324,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!'' +->''The 'install' command does NOT process dependencies and it is usually +recommended to use 'depinst' (next) instead!'' [@ $ prt-get depinst xterm @@ -304,9 +355,10 @@ $ 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.'' +->''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}' @] @@ -315,18 +367,29 @@ $ prt-get isinst $(prt-get quickdep $(prt-get quickdiff)) | awk '/not installed/ !!!! /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' of ports prt-get should check in its operation. By default +the 'core', 'opt', and 'xorg' collections are enabled. The 'compat-32' and +'contrib' collections are disabled by default, see sections "Enabling the +'contrib' collection" and "Enabling the 'compat-32' collection". -%fn%logfile%% - This option configures a file for prt-get to log its operation if desired. +%fn%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 @@ -335,22 +398,26 @@ 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 @] -Another case where this might be useful would be that of replacing a slow-compiling source port with a precompiled binary -port in order to save time. For example the following would indicate that '%fn%rust-bin%%' is considered sufficient to -satisfy a dependency on '%fn%rust%%' in a port: +Another case where aliases might be useful would be that of replacing a +slow-compiling source port with a precompiled binary port in order to save time. +For example the following would indicate that '%fn%rust-bin%%' is considered +sufficient to satisfy a dependency on '%fn%rust%%' in a port: [@ rust-bin: rust @@ -358,25 +425,32 @@ rust-bin: rust ->%lfloat%http://crux.nu/doc/images/note.png '''Note'''[[]] -->''prt-get's alias function does NOT automatically replace ports during an install or depinst operation. If a port -depends on '%fn%rust%%' and neither '%fn%rust-bin%%' or '%fn%rust%%' are installed, prt-get will install '%fn%rust%%' as -listed in the port's dependencies. If '%fn%rust-bin%%' is installed before the depending port's install or depinst -operation, on the other hand, '''prt-get''' will consider the dependency satisfied.'' +->''prt-get's alias function does NOT automatically replace ports during an +install or depinst operation. If a port depends on '%fn%rust%%' and neither +'%fn%rust-bin%%' or '%fn%rust%%' are installed, prt-get will install +'%fn%rust%%' as listed in the port's dependencies. If '%fn%rust-bin%%' is +installed before the depending port's install or depinst operation, on the other +hand, '''prt-get''' will consider the dependency satisfied.'' -This is NOT an exhaustive list of all of '''prt-get''''s commands, features, and configuration options, merely a starting -point. More information can be found in the [[https://crux.nu/doc/prt-get%20-%20User%20Manual.html | manual]] and -[[https://crux.nu/doc/prt-get%20-%20Quick%20start.html | quick start]] documentation. +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. @@ -420,7 +494,8 @@ 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 @@ -443,41 +518,58 @@ 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'''.'' +->''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%''#-''.pkg.tar.gz%%. -Before the package creation is completed, '''pkgmk''' will check the content of the package against the %fn%.footprint%% -file. If this file does not exist, it will be created and the test will be skipped. -The %fn%.footprint%% file will contain a list of all files that should be in the package if the build was successful or a -list of all the files that were installed in %fn%$PKG%% (if the %fn%.footprint%% did not already exist). If there is a -mismatch the test will fail and an error message will be printed. You should not write the %fn%.footprint%% file by hand. -Instead, when a package has been upgraded and you need to update the contents of the %fn%.footprint%% file you simply do -'''pkgmk -uf'''. This test ensures that a rebuild of the package turned out as expected. +When the build() function has been executed, the %fn%$PKG%% directory will be +made into a package named fn%''#-''.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 [[https://crux.nu/Main/PortGuidelines | PortGuidelines]] for additional information''.'' +->''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: +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!''' +* 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_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 +* 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: @@ -485,55 +577,70 @@ 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. -!! 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%%. +* 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. +* Do not combine several separately distributed programs/libraries into one +package. Make several packages instead. -* The build function should never touch anything outside the work directory, and ideally should not rely on having -an internet connection (say, to download sources not listed in the %fn%source%% array). While '''pkgmk''' does not -currently recognize git urls in the %fn%source%% array, efforts are underway to add this feature, thereby removing the -temptation to write a build function that reaches out to the internet for the latest git source tree. +* The build function should never touch anything outside the work directory, and +ideally should not rely on having an internet connection (say, to download +sources not listed in the %fn%source%% array). While '''pkgmk''' does not +currently recognize git urls in the %fn%source%% array, efforts are underway +to add this feature, thereby removing the temptation to write a build function +that reaches out to the internet for the latest git source tree. --> The motivation for a policy of separating 'download' from 'build' is that a user with intermittent internet access -should be able to run @@pkgmk -do@@ in the directory of every outdated package, and then go offline to finish the sysup -operation. Language-specific toolchains, like those embraced by rust and python (cargo and pip, respectively), are making -this policy more difficult to enforce. You are free to forego CRUX pkgutils and let the ecosystems of the ''N'' different -languages manage their respective software in separate subdirectories (like python's %fn%~/.local/share/virtualenv%% or -rust's %fn%~/.cargo%%), at the expense of having to learn '''N+1''' administration suites rather than just the 1 suite of -CRUX pkgutils. Every language-specific project that appears in the official repositories represents a hard-won effort by -the CRUX development team to sustain the historic method of software deployment, in the face of software development -trends all heading away from this model. +-> The motivation for a policy of separating 'download' from 'build' is that a +user with intermittent internet access should be able to run @@pkgmk -do@@ in +the directory of every outdated package, and then go offline to finish the sysup +operation. Language-specific toolchains, like those embraced by rust and python +(cargo and pip, respectively), are making this policy more difficult to enforce. +You are free to forego CRUX pkgutils and let the ecosystems of the ''N'' +different languages manage their respective software in separate subdirectories +(like python's %fn%~/.local/share/virtualenv%% or rust's %fn%~/.cargo%%), at the +expense of having to learn '''N+1''' administration suites rather than just the +1 suite of CRUX pkgutils. Every language-specific project that appears in the +official repositories represents a hard-won effort by the CRUX development team +to sustain the historic method of software deployment, in the face of software +development trends all heading away from this model. !!! Directories -* In general packages should install files in these directories. Exceptions are of course allowed if there is a good reason. But try to follow the following directory structure as close as possible. +* In general packages should install files in these directories. Exceptions are +of course allowed if there is a good reason. But try to follow the following +directory structure as close as possible. >>margin-left=40px ||cellpadding="3" rules="all" frame="box" @@ -549,23 +656,44 @@ trends all heading away from this model. ||%fn%/etc/%% ||Configuration files for system software (daemons, etc) >> -* %fn%/opt%% directory is reserved for manually compiled/installed applications. Packages should never place anything there. -* %fn%/usr/libexec/%% is not used in CRUX, thus packages should never install anything there. Use %fn%/usr/lib//%% instead. +* %fn%/opt%% directory is reserved for manually compiled/installed applications. +Packages should never place anything there. + +* %fn%/usr/libexec/%% is not used in CRUX, thus packages should never install +anything there. Use %fn%/usr/lib//%% instead. !!! Remove Junk Files -* Packages should not contain “junk files”. This includes info pages and other online documentation, man pages excluded (e.g. %fn%usr/doc/*%%, %fn%README%%, %fn%*.info%%, %fn%*.html%%, etc). -* Files related to NLS (national language support), always use '''--disable-nls''' when available. -* Useless or obsolete binaries (e.g. %fn%/usr/games/banner%% and %fn%/sbin/mkfs.minix%%). +* Packages should not contain “junk files”. This includes info pages +and other online documentation, man pages excluded (e.g. %fn%usr/doc/*%%, +%fn%README%%, %fn%*.info%%, %fn%*.html%%, etc). + +* Files related to NLS (national language support), always use +'''--disable-nls''' when available. + +* Useless or obsolete binaries (e.g. %fn%/usr/games/banner%% and +%fn%/sbin/mkfs.minix%%). !!! Pkgfile -* Do not add new variables to the %fn%Pkgfile%%. Only in very few cases does this actually improve the readability or the quality of the package. Further, the only variables that are guranteed to work with future versions of '''pkgmk''' are @@name@@, @@version@@, @@release@@, and @@source@@. Other names could be in conflict with internal variables in '''pkgmk'''. -* Use the @@$name@@ and @@$version@@ variables to make the package easier to update/maintain. For example, [=source=(http://xyz.org/$name-$version.tar.gz)=] is better than [=source=(http://xyz.org/myprog-1.0.3.tar.gz)=] since the URL will automatically updated when you modify the @@$version@@ variable. +* Do not add new variables to the %fn%Pkgfile%%. Only in very few cases does +this actually improve the readability or the quality of the package. Further, +the only variables that are guranteed to work with future versions of +'''pkgmk''' are @@name@@, @@version@@, @@release@@, and @@source@@. Other +names could be in conflict with internal variables in '''pkgmk'''. + +* Use the @@$name@@ and @@$version@@ variables to make the package easier to +update/maintain. For example, [=source=(http://xyz.org/$name-$version.tar.gz)=] +is better than [=source=(http://xyz.org/myprog-1.0.3.tar.gz)=] since the URL +will automatically updated when you modify the @@$version@@ variable. + * Remember that @@source@@ is an array, i.e. always do @@source=(...)@@ and not @@source=...@@ -* Another array that '''pkgmk''' will make use of, if defined, is @@renames@@ (introduced in CRUX 3.7). This array lets -you save the downloaded source tarballs with a more descriptive filename, to avoid filename collisions when using a shared -directory for downloads. See the %fn%Pkgfile%% man page for more details. + +* Another array that '''pkgmk''' will make use of, if defined, is @@renames@@ +(introduced in CRUX 3.7). This array lets you save the downloaded source +tarballs with a more descriptive filename, to avoid filename collisions when +using a shared directory for downloads. See the %fn%Pkgfile%% man page for more +details. !!!! Pkgfile header @@ -579,7 +707,8 @@ Provide a header including the following fields: ||URL||A webpage with more information on this software package|| ||Depends on||A list of dependencies, separated either by spaces or commas|| -@@Depends on@@ can be omitted if there are no dependencies; @@Packager@@ can be omitted if the maintainer and packager are the same person. +@@Depends on@@ can be omitted if there are no dependencies; @@Packager@@ can be +omitted if the maintainer and packager are the same person. '''Example header''' diff --git a/crux-wiki/Handbook3-7-Ports b/crux-wiki/Handbook3-7-Ports index 9e667a9..49c5578 100644 --- a/crux-wiki/Handbook3-7-Ports +++ b/crux-wiki/Handbook3-7-Ports @@ -2,43 +2,72 @@ !! Introduction !!! What is a Port? -A port is a directory containing the files needed for building a package using '''pkgmk'''. This means that this directory at least has the files %fn%Pkgfile%% (which is the package build description) and %fn%.footprint%% (which is used for regression testing and contains a list of files this package is expected to contain once it is built). Further, a port directory can contain patches and/or other files needed for building the package. It is important to understand that the actual source code for the package is not necessarily present in port directory. Instead the %fn%Pkgfile%% contains an URL which points to a location where the source can be downloaded. +A port is a directory containing the files needed for building a package using +'''pkgmk'''. This means that this directory at least has the files %fn%Pkgfile%% +(which is the package build description) and %fn%.footprint%% (which is used for +regression testing and contains a list of files this package is expected to +contain once it is built). Further, a port directory can contain patches and/or +other files needed for building the package. It is important to understand that +the actual source code for the package is not necessarily present in port +directory. Instead the %fn%Pkgfile%% contains an URL which points to a location +where the source can be downloaded. -The use of the word ''port'' in this context is borrowed from the BSD world, where a ''port'' refers to a program that has been ported to a system or platform. The word can sometimes be a bit misleading since most programs require no actual porting to run on CRUX (or on Linux in general). +The use of the word ''port'' in this context is borrowed from the BSD world, +where a ''port'' refers to a program that has been ported to a system or +platform. The word can sometimes be a bit misleading since most programs require +no actual porting to run on CRUX (or on Linux in general). !!! What is the Ports System? -The term ''Ports System'' refers to a remote repository containing ports and a client program capable of downloading ports from that repository. The administrator of -a CRUX system runs the '''ports(8)''' bash script to download ports from the remote repository and place them in %fn%/usr/ports/%%. The '''ports''' script uses -rsync(1) or httpup(1) or git(1) to do the actual downloading/synchronization. +The term ''Ports System'' refers to a remote repository containing ports and a +client program capable of downloading ports from that repository. The +administrator of a CRUX system runs the '''ports(8)''' bash script to download +ports from the remote repository and place them in %fn%/usr/ports/%%. The +'''ports''' script uses rsync(1) or httpup(1) or git(1) to do the actual +downloading/synchronization. !!! Port collections -CRUX ports are organized in so-called 'collections'. There are three different layers of ports: +CRUX ports are organized in so-called 'collections'. There are three different +layers of ports: !!!! The official collections 'core', 'opt', 'xorg' and 'compat-32' -%fn%core%%, %fn%opt%%, %fn%xorg%% and %fn%compat-32%% are the four primary collections of CRUX. They're maintained by the CRUX development team which ensures that they're consistent and working well together. The first three are enabled by default. The %fn%compat-32%% collection is disabled by default and contains 32-bit compatibility ports. +%fn%core%%, %fn%opt%%, %fn%xorg%% and %fn%compat-32%% are the four primary +collections of CRUX. They're maintained by the CRUX development team which +ensures that they're consistent and working well together. The first three are +enabled by default. The %fn%compat-32%% collection is disabled by default and +contains 32-bit compatibility ports. !!!! The user contributed collection 'contrib' -The %fn%contrib%% collection is a collection which is provided by experienced port maintainers: some are part of the CRUX development team, while others are regular users. Its goal is to reduce the number of duplicate ports provided in the individual collections. If you're a seasoned port maintainer, you might even want to join the contrib collection. +The %fn%contrib%% collection is a collection which is provided by experienced +port maintainers: some are part of the CRUX development team, while others are +regular users. Its goal is to reduce the number of duplicate ports provided in +the individual collections. If you're a seasoned port maintainer, you might +even want to join the contrib collection. -As those ports are not provided officially by the CRUX development team, this collection is disabled by default. +As those ports are not provided officially by the CRUX development team, this +collection is disabled by default. !!!! The individual collections from CRUX users -Using [[HttpUp]] or git, every user can publish his or her own ports easily; the only requirement for that is some -webspace to upload the ports. Maintaining an HttpUp repository of ports, which you've tested and gotten successfully -running, is a simple way to contribute back to the CRUX community. +Using [[HttpUp]] or git, every user can publish his or her own ports easily; the +only requirement for that is some webspace to upload the ports. Maintaining an +HttpUp repository of ports, which you've tested and gotten successfully running, +is a simple way to contribute back to the CRUX community. !! Using the Ports System !!! Synchronizing Your Local Ports Structure -When CRUX is installed for the first time the local ports structure (%fn%/usr/ports/%%) is empty. To bring your local ports structure up to date you use the '''ports''' utility with the '''-u''' option. Example: +When CRUX is installed for the first time the local ports structure +(%fn%/usr/ports/%%) is empty. To bring your local ports structure up to date you +use the '''ports''' utility with the '''-u''' option. Example: $ ports -u -The '''-u''' option means update, and tells '''ports''' to contact the ports repository and download new and updated ports. The output from this execution is something like this: +The '''-u''' option means update, and tells '''ports''' to contact the ports +repository and download new and updated ports. The output from this execution is +something like this: Updating file list from crux.nu::ports/crux-3.7/core/ Updating collection ports/crux-3.7/core/ @@ -55,11 +84,50 @@ The output reveals which files are downloaded, updated and deleted. !!! Listing Local Ports -When the local ports structure has been updated the directory %fn%/usr/ports/%% will contain two package categories, %fn%core%% and %fn%opt%%. Under each of these directories you will find ports. You can simply browse around in the directory structure to find out which ports are available. +When the local ports structure has been updated the directory %fn%/usr/ports/%% +will contain two package categories, %fn%core%% and %fn%opt%%. Under each of +these directories you will find ports. You can simply browse around in the +directory structure to find out which ports are available. $ cd /usr/ports/core/ $ ls + acl/ gperf/ openssh/ + attr/ grep/ openssl/ + autoconf/ groff/ patch/ + automake/ gzip/ pciutils/ + bash/ hdparm/ perl/ + bc/ httpup/ pkgconf/ + binutils/ iana-etc/ pkgutils/ + bison/ inetutils/ ports/ + bzip2/ iproute2/ procps/ + ca-certificates/ iptables/ prt-get/ + COPYING kbd/ psmisc/ + COPYRIGHT kmod/ python3/ + coreutils/ less/ rc/ + cpio/ libarchive/ rdate/ + curl/ libcap/ readline/ + dash/ libdevmapper/ rsync/ + db/ libffi/ sed/ + dcron/ libgmp/ shadow/ + dhcpcd/ libmpc/ signify/ + diffutils/ libmpfr/ sqlite3/ + e2fsprogs/ libnsl/ start-stop-daemon/ + ed/ libpcre/ sudo/ + elfutils/ libpipeline/ sysfsutils/ + eudev/ libtirpc/ sysklogd/ + exim/ libtool/ sysvinit/ + expat/ libusb/ tar/ + file/ linux-pam/ time/ + filesystem/ lzo/ tzdata/ + findutils/ m4/ usbutils/ + flex/ make/ util-linux/ + gawk/ man-db/ vim/ + gcc/ man-pages/ wget/ + gdbm/ mlocate/ which/ + gettext/ mpdecimal/ xz/ + glibc/ nasm/ zlib/ + glibc-32/ ncurses/ zstd/ You can also use '''ports''' with the '''-l''' option to list all local ports. Example: @@ -73,34 +141,46 @@ You can also use '''ports''' with the '''-l''' option to list all local ports. E core/binutils ... -If you are looking for a specific package, it might be easier to use this approach (e.g. @@ports -l | grep sendmail@@) to find out if the package is available and if so in which category it is located. +If you are looking for a specific package, it might be easier to use this +approach (e.g. @@ports -l | grep sendmail@@) to find out if the package is +available and if so in which category it is located. !!! Listing Version Differences -To find out if the ports structure carries ports that are different (likely newer) compared to the versions currently installed you can use the option '''-d'''. If version differences are found, the output from the above command could look something like this: +To find out if the ports structure carries ports that are different (likely +newer) compared to the versions currently installed you can use the option +'''-d'''. If version differences are found, the output from the above command +could look something like this: $ ports -d Collection Name Port Installed core glibc 2.3.6-3 2.3.6-2 opt gtk 2.8.12-1 2.8.11-1 -If no version differences were found, i.e. the system is in sync with the ports structure, the output will simply be: +If no version differences were found, i.e. the system is in sync with the ports +structure, the output will simply be: $ ports -d No differences found !!! Building and Installing Packages -Once you have found a port that you want to build and install you simply go into the desired port directory and use '''pkgmk''' to build it. Example: +Once you have found a port that you want to build and install you simply go into +the desired port directory and use '''pkgmk''' to build it. Example: $ cd /usr/ports/core/gawk $ pkgmk -d -The '''-d''' option means download missing source files and tells '''pkgmk''' to download the source(s) specified in the Pkgfile (in case the source is already downloaded this option is ignored). When the download is completed the package will be built. If the package was built successfully you can use '''pkgadd''' to install or upgrade it. Example: +The '''-d''' option means download missing source files and tells '''pkgmk''' to +download the source(s) specified in the Pkgfile (in case the source is already +downloaded this option is ignored). When the download is completed the package +will be built. If the package was built successfully you can use '''pkgadd''' to +install or upgrade it. Example: $ pkgadd gawk#3.1.5-3.pkg.tar.gz -To make life a bit easier these two steps can be made into one by using the options '''-i''' (for install) or '''-u''' (for upgrade). Example: +To make life a bit easier these two steps can be made into one by using the +options '''-i''' (for install) or '''-u''' (for upgrade). Example: $ pkgmk -d -i @@ -108,24 +188,29 @@ or $ pkgmk -d -u -This will download, build and then install/upgrade the package. Note that the package will only be installed/upgraded if the build is successful. +This will download, build and then install/upgrade the package. Note that the +package will only be installed/upgraded if the build is successful. !!! Enabling the 'contrib' collection -As previously mentioned, the 'contrib' collection contains useful ports of experienced port maintainers. Since they are -not provided by the CRUX development team, you should be slightly more critical with respect to quality and security. -However, members with write permissions for 'contrib' are usually well-known and active in the CRUX community. +As previously mentioned, the 'contrib' collection contains useful ports of +experienced port maintainers. Since they are not provided by the CRUX +development team, you should be slightly more critical with respect to quality +and security. However, members with write permissions for 'contrib' are usually +well-known and active in the CRUX community. -To enable the 'contrib' collection so that @@ports -u@@ will bring it up to date, just rename its rsync file. +To enable the 'contrib' collection so that @@ports -u@@ will bring it up to +date, just rename its rsync file. [@ $ cd /etc/ports $ mv contrib.rsync.inactive contrib.rsync @] -You will probably also want to let %fn%prt-get%% know about the newly-enabled 'contrib' tree. This can be done by editing -%fn%/etc/prt-get.conf%% and uncommenting the line @@prtdir /usr/ports/contrib@@ (i.e. remove the hashmark in the beginning of -the line. After that, it should look like this: +You will probably also want to let %fn%prt-get%% know about the newly-enabled +'contrib' tree. This can be done by editing fn%/etc/prt-get.conf%% and +uncommenting the line @@prtdir /usr/ports/contrib@@ (i.e. remove the hashmark in +the beginning of the line. After that, it should look like this: [@ ### @@ -144,7 +229,8 @@ Now, run @@ports -u@@ and you're ready to use the ports from %fn%contrib%%. !!! Enabling the 'compat-32' collection -The 'compat-32' collection contains compatibility ports needed for 32-bit support (32-bit applications running on a 64-bit multilib system.) +The 'compat-32' collection contains compatibility ports needed for 32-bit +support (32-bit applications running on a 64-bit multilib system.) To enable it for %fn%ports%%, do @@ -153,43 +239,55 @@ $ cd /etc/ports $ mv compat-32.rsync.inactive compat-32.rsync @] -The 'compat-32' collection is enabled in the same way as the 'contrib' collection (described previously) for usage with %fn%prt-get%%. +The 'compat-32' collection is enabled in the same way as the 'contrib' +collection (described previously) for usage with %fn%prt-get%%. -As with 'contrib', run @@ports -u@@ and you're ready to use the ports from %fn%compat-32%%. +As with 'contrib', run @@ports -u@@ and you're ready to use the ports from +%fn%compat-32%%. !!! Additional tools !!!! Building ports as unprivileged user -Building packages requires root privileges in order to create files with the correct owner and group. This is a security -concern because a malicious or badly designed port can run arbitrary commands when its Pkgfile is sourced by the shell. -The '''fakeroot''' command provides a way to build ports as normal user. Particularly when you build packages from user -contributed repositories you are advised to use '''fakeroot''': +Building packages requires root privileges in order to create files with the +correct owner and group. This is a security concern because a malicious or badly +designed port can run arbitrary commands when its Pkgfile is sourced by the +shell. The '''fakeroot''' command provides a way to build ports as normal user. +Particularly when you build packages from user contributed repositories you are +advised to use '''fakeroot''': [@ $ fakeroot pkgmk -d @] -* You can also make '''prt-get''' use '''fakeroot''', by modifying the line in %fn%prt-get.conf%% that contains -@@makecommand@@. This line would allow a non-root user running @@prt-get@@ to create packages with no footprint mismatches -(wrong owner/group), but the installation of these packages (and the running of pre-/post-install scripts) needs additional -privileges. +* You can also make '''prt-get''' use '''fakeroot''', by modifying the line in +%fn%prt-get.conf%% that contains @@makecommand@@. This line would allow a +non-root user running @@prt-get@@ to create packages with no footprint +mismatches (wrong owner/group), but the installation of these packages (and +the running of pre-/post-install scripts) needs additional privileges. -* Additional lines in %fn%prt-get.conf%%, defining @@addcommand@@ and @@runscriptcommand@@ with '''sudo''' or -'''doas''', is one way to let @@prt-get@@ work properly for a non-root user. +* Additional lines in %fn%prt-get.conf%%, defining @@addcommand@@ and +@@runscriptcommand@@ with '''sudo''' or '''doas''', is one way to let +@@prt-get@@ work properly for a non-root user. -* Another possibility is to write a '''sudo''' or '''doas''' configuration that grants permission to run @@prt-get@@ -itself, and then as a non-root user you would always run @@sudo prt-get@@ rather than @@prt-get@@ directly. +* Another possibility is to write a '''sudo''' or '''doas''' configuration that +grants permission to run @@prt-get@@ itself, and then as a non-root user you +would always run @@sudo prt-get@@ rather than @@prt-get@@ directly. -* Read the man pages for %fn%prt-get.conf%% and %fn%sudo/doas%% to learn how these pieces fit together, and choose whichever -option you like best. To give extra scrutiny to ports you find outside the official repositories, it helps to -restrict yourself to low-level commands @@pkgmk@@ and @@pkgadd@@ rather than the wrapper program @@prt-get@@. This -practice forces you to be in the directory of the unofficial port, where the %fn%Pkgfile%% source array and build function -are more likely to receive your careful attention. +* Read the man pages for %fn%prt-get.conf%% and %fn%sudo/doas%% to learn how +these pieces fit together, and choose whichever option you like best. To give +extra scrutiny to ports you find outside the official repositories, it helps to +restrict yourself to low-level commands @@pkgmk@@ and @@pkgadd@@ rather than the +wrapper program @@prt-get@@. This practice forces you to be in the directory of +the unofficial port, where the %fn%Pkgfile%% source array and build function are +more likely to receive your careful attention. !!!! Useful scripts -Regarding package and ports management there are many tasks which can be done in several steps with the CRUX standard -tools introduced above. The %fn%opt%% repository contains a port called [[PrtUtils|prt-utils]] with many such scripts. -Other combinations of low-level tools, using UNIX pipes, command substitution, and text processing utilities, can be found -in the bug tracker, the mailing list, and IRC logs. Efforts are underway to bring this diaspora of institutional knowledge -into a central place, such as the EXAMPLES section of the most relevant man page. +Regarding package and ports management there are many tasks which can be done in +several steps with the CRUX standard tools introduced above. The %fn%opt%% +repository contains a port called [[PrtUtils|prt-utils]] with many such scripts. +Other combinations of low-level tools, using UNIX pipes, command substitution, +and text processing utilities, can be found in the bug tracker, the mailing +list, and IRC logs. Efforts are underway to bring this diaspora of institutional +knowledge into a central place, such as the EXAMPLES section of the most +relevant man page.