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

Handbook 3.7: minor formatting fixes

This commit is contained in:
John McQuah 2022-08-05 11:56:44 -04:00
parent 7a0e0f04b8
commit 71c841f91d
4 changed files with 559 additions and 263 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

125
crux-wiki/Handbook3-7-Configuration
View File

@ -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.

66
crux-wiki/Handbook3-7-Intro
View File

@ -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.

425
crux-wiki/Handbook3-7-Package
View File

@ -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%''<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 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 &#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 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 &#8220;/&#8221; since you are referring to the files in the package, not the
files on the disk.''
->''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
@ -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%''<name>#<version>-<release>''.pkg.tar.gz%%.
Before the package creation is completed, '''pkgmk''' will check the content of the package against the %fn%.footprint%%
file. If this file does not exist, it will be created and the test will be skipped.
The %fn%.footprint%% file will contain a list of all files that should be in the package if the build was successful or a
list of all the files that were installed in %fn%$PKG%% (if the %fn%.footprint%% did not already exist). If there is a
mismatch the test will fail and an error message will be printed. You should not write the %fn%.footprint%% file by hand.
Instead, when a package has been upgraded and you need to update the contents of the %fn%.footprint%% file you simply do
'''pkgmk -uf'''. This test ensures that a rebuild of the package turned out as expected.
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 [[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/<prog>/%% 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/<prog>/%% instead.
!!! Remove Junk Files
* Packages should not contain &#8220;junk files&#8221;. This includes info pages and other online documentation, man pages excluded (e.g. %fn%usr/doc/*%%, %fn%README%%, %fn%*.info%%, %fn%*.html%%, etc).
* Files related to NLS (national language support), always use '''--disable-nls''' when available.
* Useless or obsolete binaries (e.g. %fn%/usr/games/banner%% and %fn%/sbin/mkfs.minix%%).
* Packages should not contain &#8220;junk files&#8221;. This includes info pages
and other online documentation, man pages excluded (e.g. %fn%usr/doc/*%%,
%fn%README%%, %fn%*.info%%, %fn%*.html%%, etc).
* Files related to NLS (national language support), always use
'''--disable-nls''' when available.
* Useless or obsolete binaries (e.g. %fn%/usr/games/banner%% and
%fn%/sbin/mkfs.minix%%).
!!! Pkgfile
* Do not add new variables to the %fn%Pkgfile%%. Only in very few cases does this actually improve the readability or the quality of the package. Further, the only variables that are guranteed to work with future versions of '''pkgmk''' are @@name@@, @@version@@, @@release@@, and @@source@@. Other names could be in conflict with internal variables in '''pkgmk'''.
* Use the @@$name@@ and @@$version@@ variables to make the package easier to update/maintain. For example, [=source=(http://xyz.org/$name-$version.tar.gz)=] is better than [=source=(http://xyz.org/myprog-1.0.3.tar.gz)=] since the URL will automatically updated when you modify the @@$version@@ variable.
* 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'''

206
crux-wiki/Handbook3-7-Ports
View File

@ -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.