Documentation/crux-wiki/Handbook3-7-Ports

! The Ports System
!! Introduction
!!! What is a Port?

A port is a directory containing the files needed for building a package using
'''pkgmk'''. This means that this directory at least has the files %fn%Pkgfile%%
(which is the package build description) and %fn%.footprint%% (which is used for
regression testing and contains a list of files this package is expected to
contain once it is built). Further, a port directory can contain patches and/or
other files needed for building the package. It is important to understand that
the actual source code for the package is not necessarily present in port
directory. Instead the %fn%Pkgfile%% contains an URL which points to a location
where the source can be downloaded.

The use of the word ''port'' in this context is borrowed from the BSD world,
where a ''port'' refers to a program that has been ported to a system or
platform. The word can sometimes be a bit misleading since most programs require
no actual porting to run on CRUX (or on Linux in general).

!!! What is the Ports System?

The term ''Ports System'' refers to a remote repository containing ports and a
client program capable of downloading ports from that repository. The
administrator of a CRUX system runs the '''ports(8)''' bash script to download
ports from the remote repository and place them in %fn%/usr/ports/%%. The
'''ports''' script uses rsync(1) or httpup(1) or git(1) to do the actual
downloading/synchronization.

!!! Port collections

CRUX ports are organized in so-called 'collections'. There are three different
layers of ports:

!!!! The official collections 'core', 'opt', 'xorg' and 'compat-32'

%fn%core%%, %fn%opt%%, %fn%xorg%% and %fn%compat-32%% are the four primary
collections of CRUX. They're maintained by the CRUX development team which
ensures that they're consistent and working well together. The first three are
enabled by default. The %fn%compat-32%% collection is disabled by default and
contains 32-bit compatibility ports.

!!!! The user contributed collection 'contrib'
The %fn%contrib%% collection is a collection which is provided by experienced
port maintainers: some are part of the CRUX development team, while others are
regular users. Its goal is to reduce the number of duplicate ports provided in
the individual collections.  If you're a seasoned port maintainer, you might
even want to [[ContribRules|join the contrib team]].

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 [[SettingUpAnHttpupRepo|HttpUp]] or [[SettingUpAGitRepo|git]], every
user can publish his or her own ports easily; the only requirement for that
is some webspace to upload the ports. Maintaining an HttpUp repository of
ports, which you've tested and gotten successfully running, is a simple way
to contribute back to the CRUX community.

!! Using the Ports System
!!! Synchronizing Your Local Ports Structure

When CRUX is installed for the first time the local ports structure
(%fn%/usr/ports/%%) is empty. To bring your local ports structure up to date you
use the '''ports''' utility with the '''-u''' option. Example:

 $ ports -u

The '''-u''' option means update, and tells '''ports''' to contact the ports
repository and download new and updated ports. The output from this execution is
something like this:

 Updating file list from crux.nu::ports/crux-3.7/core/
 Updating collection ports/crux-3.7/core/
 ...
 Updating file list from crux.nu::ports/crux-3.7/opt/
 Updating collection ports/crux-3.7/opt/
 ...
 Updating file list from crux.nu::ports/crux-3.7/xorg/
 Updating collection ports/crux-3.7/xorg/
 ...
 Finished successfully

The output reveals which files are downloaded, updated and deleted.

!!! Listing Local Ports

When the local ports structure has been updated the directory %fn%/usr/ports/%%
will contain at least two collections, %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/			httpup/			nftables/
 attr/			iana-etc/		ninja/
 autoconf/		inetutils/		openssh/
 automake/		iproute2/		openssl/
 bash/			iptables/		patch/
 bc/			jansson/		pciutils/
 binutils/		jsoncpp/		perl/
 bison/			kbd/			pkgconf/
 bzip2/			kmod/			pkgutils/
 ca-certificates/	less/			ports/
 cmake/			libarchive/		procps/
 coreutils/		libcap/			prt-get/
 cpio/			libdevmapper/		psmisc/
 curl/			libedit/		python3/
 dash/			libffi/			python3-setuptools/
 db/			libgmp/			rc/
 dcron/			libmnl/			rdate/
 dhcpcd/		libmpc/			readline/
 diffutils/		libmpfr/		rhash/
 dumb_runtime_dir/	libnftnl/		rsync/
 e2fsprogs/		libnghttp2/		sed/
 ed/			libnsl/			shadow/
 elfutils/		libpcre/		signify/
 eudev/			libpcre2/		sqlite3/
 exim/			libpipeline/		start-stop-daemon/
 expat/			libtirpc/		sudo/
 file/			libtool/		sysfsutils/
 filesystem/		libusb/			sysklogd/
 findutils/		libuv/			sysvinit/
 flex/			linux-pam/		tar/
 gawk/			lzlib/			time/
 gcc/			lzo/			tzdata/
 gdbm/			m4/			usbutils/
 gettext/		make/			util-linux/
 glibc/			man-db/			vim/
 glibc-32/		man-pages/		which/
 gperf/			meson/			xz/
 grep/			mlocate/		zlib/
 groff/			mpdecimal/		zstd/
 gzip/			nasm/
 hdparm/		ncurses/

You can also use '''ports''' with the '''-l''' option to list all local ports. Example:

 $ ports -l
 core/acl
 core/attr
 core/autoconf
 core/automake
 core/bash
 core/bc
 ...

If you are looking for a specific package, a command like @@ports -l | grep sendmail@@
provides a straightforward way to find out if the package is available and if so
in which collection it is located. More complicated searches (eg., based on
footprint, description, or maintainer) can be performed using @@prt-get@@.

!!! 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 differences are found (in either 'version' or 'release'), the
output from the above command could look something like this:

 $ ports -d
 Collection  Name     Port      Installed
 contrib     pipewire 0.3.56-1  0.3.55-1
 xorg        mesa     22.1.5-1  22.1.4-1

If no version differences were found, i.e. the system is in sync with the ports
structure, the output will simply be:

 $ ports -d
 No differences found

!!! Building and Installing Packages

Once you have found a port that you want to build and install you simply go into
the desired port directory and use '''pkgmk''' to build it. Example:

 $ cd /usr/ports/core/gawk
 $ pkgmk -d

The '''-d''' option means download missing source files and tells '''pkgmk''' to
download the source(s) specified in the Pkgfile (in case the source is already
downloaded, this option is ignored). When the download is completed the package
will be built. If the package was built successfully you can use '''pkgadd''' to
install or upgrade it. Example:

 $ pkgadd gawk#3.1.5-3.pkg.tar.gz

To make life a bit easier these two steps can be made into one by using the
options '''-i''' (for install) or '''-u''' (for upgrade). Example:

 $ pkgmk -d -i

or

 $ pkgmk -d -u

This will download, build and then install/upgrade the package. Note that the
package will only be installed/upgraded if the build is successful.

-> If you enable [[#NonRootBuilding | building ports as an unprivileged user]]
and give that user write permissions on the directories for pkgmk {sources, work,
packages}, the unprivileged user will be able to create a package but not to
exercise the '''-i''' and '''-u''' options of '''pkgmk'''. There are forks of
pkgmk that automatically invoke '''sudo''' or '''doas''' when performing the
'''pkgadd''' step, but these forks are not part of the official CRUX utilities
at this time.

!!! Enabling the 'contrib' collection

As previously mentioned, the 'contrib' collection contains useful ports of
experienced port maintainers. Since they are not provided by the CRUX
development team, you should be slightly more critical with respect to quality
and security. However, members with write permissions for 'contrib' are usually
well-known and active in the CRUX community.

To enable the 'contrib' collection so that @@ports -u@@ will bring it up to
date, just rename its rsync file.

[@
$ cd /etc/ports
$ mv contrib.rsync.inactive contrib.rsync
@]

You will probably also want to let %fn%prt-get%% know about the newly-enabled
'contrib' tree. This can be done by editing %fn%/etc/prt-get.conf%% and
uncommenting the line @@prtdir /usr/ports/contrib@@ (i.e. remove the hashmark in
the beginning of the line). After that, it should look like this:

[@
###
### prt-get conf
###

# note: the order matters: the package found first is used
prtdir /usr/ports/core
prtdir /usr/ports/opt

# the following line enables the user maintained contrib collection
prtdir /usr/ports/contrib
@]

Now, run @@ports -u@@ and you're ready to use the ports from %fn%contrib%%.

!!! Enabling the 'compat-32' collection

The 'compat-32' collection contains compatibility ports needed for 32-bit
support (32-bit applications running on a 64-bit multilib system).

To enable it for %fn%ports%%, do

[@
$ cd /etc/ports
$ mv compat-32.rsync.inactive compat-32.rsync
@]

The 'compat-32' collection is enabled in the same way as the 'contrib'
collection (described previously) for usage with %fn%prt-get%%.

As with 'contrib', run @@ports -u@@ and you're ready to use the ports from
%fn%compat-32%%.

!!! Additional tools
[[#NonRootBuilding]] !!!! Building ports as unprivileged user

Building packages requires root privileges in order to create files with the
correct owner and group. This is a security concern because a malicious or badly
designed port can run arbitrary commands when its Pkgfile is sourced by the
shell. The '''fakeroot''' command provides a way to build ports as normal user.
Particularly when you build packages from user contributed repositories you are
advised to use '''fakeroot''':

[@
$ fakeroot pkgmk -d
@]

* You can also make '''prt-get''' use '''fakeroot''', by modifying the line in
%fn%prt-get.conf%% that contains @@makecommand@@. This line would allow a
non-root user running @@prt-get@@ to create packages with no footprint
mismatches (wrong owner/group), but the installation of these packages (and
the running of pre-/post-install scripts) needs additional privileges.

* Additional lines in %fn%prt-get.conf%%, defining @@addcommand@@ and
@@runscriptcommand@@ with '''sudo''' or '''doas''', is one way to let
@@prt-get@@ work properly for a non-root user.

* Another possibility is to write a '''sudo''' or '''doas''' configuration that
grants permission to run @@prt-get@@ itself, and then as a non-root user you
would always run @@sudo prt-get@@ rather than @@prt-get@@ directly.

* Read the man pages for %fn%prt-get.conf%% and %fn%sudo/doas%% to learn how
these pieces fit together, and choose whichever option you like best. To give
extra scrutiny to ports you find outside the official repositories, it helps to
restrict yourself to low-level commands @@pkgmk@@ and @@pkgadd@@ rather than the
wrapper program @@prt-get@@. This practice forces you to be in the directory of
the unofficial port, where the %fn%Pkgfile%% source array and build function are
more likely to receive your careful attention.

!!!! Useful scripts

Regarding package and ports management there are many tasks which can be done in
several steps with the CRUX standard tools introduced above. The %fn%opt%%
repository contains a port called [[PrtUtils|prt-utils]] with many such scripts.
Other combinations of low-level tools, using UNIX pipes, command substitution,
and text processing utilities, can be found in the bug tracker, the mailing
list, and IRC logs. Efforts are underway to bring this diaspora of institutional
knowledge into a central place, such as the EXAMPLES section of the most
relevant man page.