summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--dev.mdwn17
-rw-r--r--dev/archive/mirroring.mdwn108
-rw-r--r--dev/multiarch.mdwn180
-rw-r--r--dev/opkbuild.mdwn4
-rw-r--r--dev/opkhelper.mdwn4
-rw-r--r--dev/releases/1/packages.mdwn55
-rw-r--r--dev/todo/install-bb-without-bb.mdwn86
-rw-r--r--dev/wolfutil.mdwn48
-rw-r--r--doc/install.mdwn8
-rw-r--r--doc/install/chroot.mdwn10
-rw-r--r--doc/install/pc.mdwn18
-rw-r--r--doc/install/prokit.mdwn84
-rw-r--r--templates/page.tmpl4
13 files changed, 518 insertions, 108 deletions
diff --git a/dev.mdwn b/dev.mdwn
index c2a910b..3b7be79 100644
--- a/dev.mdwn
+++ b/dev.mdwn
@@ -18,26 +18,21 @@ programs and libraries to be built and installed on users' systems.
Source packages have a documented [format][spf-2.0], and
[[tutorials_on_packaging|doc/pkg]] are available.
-There is always [[more_software_to_be_packaged|dev/pkg/needed]], and
-[[one_package|dev/pkg/spf-2.0]] needs to be updated to the latest package
-format. [15 packages][src_pkgs_spring2015] prepared by a team of students in
-the spring 2015 NJIT CCS Capstone program need to be reviewed for uploading to
-the package archive.
+There is always [[more_software_to_be_packaged|dev/pkg/needed]] (including Perl
+5 with cross building support), and [[one_package|dev/pkg/spf-2.0]] needs to be
+updated to the latest package format. [15 packages][src_pkgs_spring2015]
+prepared by a team of students in the spring 2015 NJIT CCS Capstone program need
+to be reviewed for uploading to the package archive.
But the work doesn't end after a package is prepared and uploaded; maintaining
existing packages is also important and neverending work. ProteanOS currently
-has [[81_source_packages_(403_binary_packages)|dev/releases/1/packages]] in its
+has [[94_source_packages_(388_binary_packages)|dev/releases/1/packages]] in its
package archive (with more not yet uploaded). Many of these have newer upstream
versions and can be updated. Some have patches that can be dropped when
updating to a newer upstream version. Some others (e.g. the toolchain packages)
have patches that may be of interest outside ProteanOS but have not yet been
submitted upstream.
-Some packages have development problems that will eventually need to be solved,
-such as [[cross_building_Perl_5|dev/pkg/needed]],
-[[multiple_tasks|dev/pkg/opkg]] in the `opkg` packaging, and adding support in
-opkg for installing packages built for foreign architectures.
-
Most source packages are maintained in [Git repositories][git-pkg]. You can
request a repository for your package on the [mailing list][proteanos-dev]. To
make changes to a package, it is recommended that you send patches to the
diff --git a/dev/archive/mirroring.mdwn b/dev/archive/mirroring.mdwn
index 9d2b38a..deabb91 100644
--- a/dev/archive/mirroring.mdwn
+++ b/dev/archive/mirroring.mdwn
@@ -1,53 +1,117 @@
[[!meta title="Mirroring the ProteanOS Package Archive"]]
-Running a mirror of the ProteanOS package archive contributes to the
+Running a public mirror of the ProteanOS package archive contributes to the
availability of ProteanOS.
-You can keep your mirror private or make it an official mirror.
+Organizations deploying many ProteanOS systems are encouraged to make local
+mirrors, which they may keep private or make public, to save bandwidth on both
+their and ProteanOS's infrastructure.
Setting up a Mirror
===================
-A mirror takes about 700 MiB of storage space as of this writing and should be
+Overview
+--------
+
+*(Impatient mirror administrators may skip this informational section and read
+the instructional sections below.)*
+
+A mirror takes about 730 MiB of storage space as of this writing and should be
expected to grow beyond that.
-The following command will list files in the archive:
+The curious may view a list of files in the archive with the following command:
$ rsync --recursive --exclude .db rsync://files.proteanos.com/proteanos
-The following command will mirror the archive:
-
- $ rsync --recursive --times --delete --exclude .db \
- > rsync://files.proteanos.com/proteanos /path/to/your/mirror/directory/
+See below for commands to copy archive files to a local mirror.
-Packages are moved from incoming into the archive four times daily. The
+Packages are processed from the incoming queue into the archive four times
+daily, so mirrors need not be updated more frequently than that. The
[[archive_management_software|dev/pro-archman]] is [configured][arch-conf] to
keep unreferenced files in the pool for one day, so mirrors must be updated at
least once a day. Otherwise, during the update, some feed index files may
-reference deleted files.
+reference deleted files. Updating at least twice daily is recommended, in case
+the synchronization source is ever temporarily unreachable.
+
+Serving the archive mirror at `/pub/proteanos` over HTTP and FTP is recommended,
+but any path and either protocol may be used. HTTP Strict Transport Security
+(HSTS) must not be used except on private mirrors used by ProteanOS systems
+known to install the `wolfssl-util` package. The ProteanOS package archive is
+already [cryptographically verified][archive-signing] using software smaller
+than a TLS implementation.
+
+Mirrors are classified by their synchronization source as either "primary" or
+"secondary" as described below. This design distributes synchronization
+bandwidth usage more efficiently across the mirror network. Secondary mirrors
+will typically update a few hours after primary mirrors do, but are otherwise
+still "first-class citizens". All mirrors regardless of classification are
+treated equally by [[dev/prokit]], the installer utility that selects a mirror.
+
+Please configure private mirrors as secondary mirrors, so as to reserve
+ProteanOS project bandwidth for those that contribute bandwidth back to the
+project.
[arch-conf]: http://files.proteanos.com/pub/proteanos/conf
+[archive-signing]:http://lists.proteanos.com/proteanos-dev/2019/04/msg00008.html
+
+Primary Public Mirror
+---------------------
+
+Primary mirrors are those that synchronize directly from
+<files.proteanos.com> and must serve their contents publicly over HTTP
+(without HSTS) and rsync and may also serve over anonymous FTP as defined by
+[IETF RFC 1635][rfc1635] with no password requirements.
+
+Run the following command one to four times (four times preferred) daily to
+synchronize your mirror:
+
+ $ rsync --recursive --times --delete --exclude .db \
+ > rsync://files.proteanos.com/proteanos /path/to/your/mirror/directory/
+
+Secondary Public or Private Mirror
+----------------------------------
+Secondary mirrors are those that synchronize from a primary mirror and serve
+their contents either publicly or privately. Public mirrors must serve over
+HTTP (without HSTS) and may also serve over anonymous FTP as defined by [IETF
+RFC 1635][rfc1635] with no password requirements. Private mirrors may serve
+over either protocol.
-Making an Official Mirror
-=========================
+Run the following command one to four times (four times preferred) daily to
+synchronize your mirror:
+
+ $ rsync --recursive --times --delete --exclude .db \
+ > ${src} /path/to/your/mirror/directory/
-Official mirror sites should make their archive mirrors available at
-`/pub/proteanos` over HTTP and FTP. Sites should also make their archive
-mirrors accessible over rsync, if possible.
+Where `${src}` is any primary mirror in the [rsync mirrors list][mirrors-rsync].
+Please try to select a primary mirror that is being used by few or no other
+secondary mirrors, to evenly spread the load across the primary mirrors.
-Once your mirror is set up, please announce it to the [ProteanOS development
-mailing list][proteanos-dev] ([list info][proteanos-dev-info]). Please include
-the following information in your announcement:
+[rfc1635]: https://tools.ietf.org/html/rfc1635
+
+
+Announcing a Public Mirror
+==========================
+
+After setting up a public mirror, please announce it to the [ProteanOS
+development mailing list][proteanos-dev] ([list info][proteanos-dev-info]).
+Please include the following information in your announcement:
* Name and e-mail address of site maintainer;
* Name and URL of site sponsor, if any;
- * Domain name, or IPv4 and/or IPv6 address, of mirror site;
- * Available protocols;
- * Country of site;
- * Frequency of mirroring; and
+ * URIs of mirror site (HTTP and/or FTP, and rsync for primary mirrors);
+ * Location (country at a minimum) of site;
+ * Synchronization frequency (or times);
+ * Synchronization source, in the case of a secondary mirror; and
* Any other comments about the site.
+Your mirror will be reviewed and added to the official mirror lists
+([HTTP][mirrors-http] and [FTP][mirrors-ftp] used by [[dev/prokit]], as well as
+[rsync][mirrors-rsync] referenced above).
+
[proteanos-dev]: mailto:proteanos-dev@lists.proteanos.com
[proteanos-dev-info]: http://lists.proteanos.com/proteanos-dev/
+[mirrors-http]: http://files.proteanos.com/pub/proteanos-mirrors-http
+[mirrors-ftp]: http://files.proteanos.com/pub/proteanos-mirrors-ftp
+[mirrors-rsync]: http://files.proteanos.com/pub/proteanos-mirrors-rsync
diff --git a/dev/multiarch.mdwn b/dev/multiarch.mdwn
new file mode 100644
index 0000000..d869a7d
--- /dev/null
+++ b/dev/multiarch.mdwn
@@ -0,0 +1,180 @@
+[[!meta title="Multiarch Design"]]
+
+Earlier design proposals are documented in [[another_page|dev/multiarch/design]]
+kept for historical purposes.
+
+
+Background
+==========
+
+ProteanOS is a self-hosting binary distribution that builds its own packages.
+It is also an embedded distribution, intended to be suitable for small
+resource-limited systems. It may not be practical to natively build all of
+ProteanOS on real hardware for every architecture to be supported. Thus, it
+will be preferable to cross-build all of ProteanOS's packages, making ProteanOS
+a highly ambitious cross-built self-hosting binary distribution.
+
+Cross-compiling and cross-assembling self-contained code is a solved problem,
+however programs typically use separately built libraries, which must be
+installed at build time to be available for compiling and linking. Sometimes,
+these dependency libraries will already be installed for use by the native
+system. So it needs to be possible to "coinstall" different architecture builds
+of each library. Package management and build tools also need to be able to
+install dependency packages of the correct architecture; for example, libraries
+must be of the *host* architecture (the architecture **for** which a package is
+being built), but build utilities must be of the *build* architecture (the
+architecture **on** which a package is being built). Further complicating
+dependency resolution, such build utilities often themselves depend on
+libraries, which must also be of the build architecture (not the host
+architecture like libraries that are direct build-dependencies). These are the
+two main problems in cross-building distribution packages: coinstallability and
+dependencies. The solution is a design known as "multiarch".
+
+ProteanOS's multiarch design is inspired by, but different from, that
+[specified][wuc-mas] and [documented][wdo-ma] in Debian and Ubuntu.
+
+ProteanOS's design solves the coinstallability and dependency problems without
+*any* modifications to its package manager, opkg-lede. This is desirable
+because opkg-lede is a tool used by many distributions separate from ProteanOS,
+and its upstream maintainers (OpenWrt) would likely be unwilling to merge and
+maintain invasive patches specific to a different distribution (making the
+patches impossible to test upstream).
+
+[wdo-ma]: http://wiki.debian.org/Multiarch
+[wuc-mas]: https://wiki.ubuntu.com/MultiarchSpec
+
+
+Design
+======
+
+Coinstallability
+----------------
+
+opkg-lede doesn't allow multiple packages to provide the same file path, so, in
+order to be coinstallable, library packages must install all of their files into
+architecture-qualified locations. [Debian and Ubuntu][wuc-mas-arch-indep-files]
+limit this requirement to only files whose contents differ between
+architectures. This is accomplished by the package manager dpkg requiring all
+packages of the same name to be the same version, verifying that shared files
+have identical contents, and reference counting shared files. As explained
+above, ProteanOS's multiarch design doesn't entail such modifications to the
+package manager.
+
+opkg-lede also doesn't allow installation of multiple packages with the same
+name and different architectures. The only way to solve this without modifying
+the package manager is to qualify the names of coinstallable packages with
+their host architectures. This will be done by appending a colon followed by
+the host architecture to each coinstallable package name, e.g. `libc.6` becomes
+`libc.6:amd64-linux-glibc`. Package names appear in the file system under
+`/var/cache/opkg/archives/` and `/var/lib/opkg/info/`, so using a colon in
+package names will prevent the use of restricted file systems such as FAT file
+systems as the root file system.
+
+Dependencies
+------------
+
+opkg-lede allows packages from different architectures to be installed, but
+there is no way to select the architecture to install other than blanket
+priority values. Since libraries of different architectures will often need to
+be installed during the same installation transaction, as described above, such
+a blunt solution is insufficient.
+
+[Debian and Ubuntu][wuc-mas-control-fields] solve this by declaring the kinds of
+dependencies each package is able to satisfy (based on the interfaces it
+provides: executables and/or libraries). Again this requires modifications to
+the package manager to affect dependency resolution. ProteanOS's design is
+similar, but implemented in a way such that *dependent* binary packages are
+responsible for declaring the architectures of *their dependencies* (which can
+be done automatically at build time, so package maintainers can focus on
+declaring how their packages satisfy dependencies, as in Debian and Ubuntu).
+
+One way to declare dependency semantics is by introducing a new single-purpose
+control field like Debian's and Ubuntu's `Multi-Arch`. However, ProteanOS will
+instead use [a control field that serves multiple purposes:
+`Section`][spf-fields-bin]. `Section: lib` packages will be automatically made
+coinstallable by opkbuild, by architecture-qualifying their names as described
+above. Library dependencies generated by oh-shlibdeps (with [a
+fix][oh-shlibdeps-host-libdirs] to be released) will automatically use the
+architecture-qualified names.
+
+ProteanOS systems should have only native architecture feeds for sections
+`boot`, `dev`, and `util` but may have multiple feeds for sections `dbg`, `lib`,
+and `libdev`. (Sections `doc`, `locale`, and `share` are
+architecture-independent.)
+
+opkg-lede's architecture priorities as described above can be useful in certain
+specific ways, through a [wrapper script that adds an `-a`/`--host-architecture`
+option][opkg-wrapper] (similar to that of apt-get). First, since multiple
+`Section: dbg` feeds may be downloaded and requiring users to
+architecture-qualify such packages would be undesirable, such packages could be
+installed instead via `opkg -a amd64-linux-glibc foo-dbg` or even simply `opkg
+install foo-dbg` for the native architecture. Similarly, `Section: libdev`
+packages as build dependencies could be automatically installed for the host
+architecture by prokit supplying an appropriate `-a` option, allowing
+maintainers to continue listing unqualified package names in `Build-Depends`
+instead of having to add `:${Host-Arch}` to every `Section: libdev` package in
+`Build-Depends`. Therefore, only `Section: lib` packages need to have
+architecture-qualified names (due to the coinstallability issue described
+above), and neither users nor maintainers are expected to manually install or
+list as dependencies such architecture-qualified packages.
+
+[wuc-mas-arch-indep-files]: https://wiki.ubuntu.com/MultiarchSpec#Architecture-independent_files_in_multiarch_packages
+[wuc-mas-control-fields]: https://wiki.ubuntu.com/MultiarchSpec#Binary_package_control_fields
+[spf-fields-bin]: http://specs.proteanos.com/spf-2.0/fields.html#fields-bin
+[oh-shlibdeps-host-libdirs]: http://git.proteanos.com/opkhelper/opkhelper.git/commit/?id=c214c727f60b070aa502b20dcc1ad7e3ce8579f2
+[opkg-wrapper]: http://git.proteanos.com/pkg/opkg-lede.git/tree/opkg
+
+
+Use Cases
+=========
+
+**Run-time dependency on a utility:** Only the native architecture of the
+utility dependency is available in the downloaded feed lists, and the dependency
+is not architecture-qualified. The native architecture will be installed.
+
+**Run-time dependency on a library:** Multiple architectures of the library
+dependency may be available, and the dependency must be qualified with the
+native architecture.
+
+**Run-time dependency on a language extension:** Despite technically being a
+shared object file, only the native architecture of the language extension
+dependency is available in the downloaded feed lists, and the dependency is not
+architecture-qualified. The language extension dependency in turn depends on a
+language interpreter, which is also not architecture-qualified. The native
+architecture of both will be installed.
+
+**Build-time dependency on a utility:** Only the build architecture of the
+utility dependency is available in the downloaded feed lists, and the dependency
+is not architecture-qualified. The build architecture will be installed.
+
+**Build-time dependency on a library:** Multiple architectures of the library
+dependency are available, and the dependency must be qualified with the host
+architecture.
+
+**Build-time dependency on a language extension:** Despite technically being a
+shared object file, only the native architecture of the language extension
+dependency is available in the downloaded feed lists, and the dependency is not
+architecture-qualified. The language extension dependency in turn depends on a
+language interpreter, which is also not architecture-qualified. The native
+architecture of both will be installed.
+
+
+Implementation
+==============
+
+File System Hierarchy
+---------------------
+
+As explained above, to be coninstallable, library packages must install all of
+their files in architecture-qualified locations. Debian and Ubuntu install
+shared object files in `/usr/lib/<triplet>` or `/lib/<triplet>`, where
+`<triplet>` is a [GNU system type][ac-systemtype]. Since multiple ProteanOS
+architectures may share the same GNU system type, ProteanOS architecture names
+are instead used in such library directories.
+
+ProteanOS's GNU Binutils and GCC packages have been patched and configured to
+use multiarch library paths since their initial releases in 2014. opkhelper has
+used multiarch library paths when configuring packages since version 3.0.0-beta1
+released in 2012.
+
+[ac-systemtype]: https://www.gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-2.69/html_node/System-Type.html
diff --git a/dev/opkbuild.mdwn b/dev/opkbuild.mdwn
index 2da4007..9e45e00 100644
--- a/dev/opkbuild.mdwn
+++ b/dev/opkbuild.mdwn
@@ -19,7 +19,7 @@ opkbuild is similar in function to the [development library][libdpkg-perl] and
Downloading
===========
-The current version of opkbuild is [4.0.2][rel-ann].
+The current version of opkbuild is [4.2.0][rel-ann].
opkbuild can be found on the ProteanOS files site by [HTTP][dl-http] or
[FTP][dl-ftp].
@@ -27,7 +27,7 @@ opkbuild can be found on the ProteanOS files site by [HTTP][dl-http] or
opkbuild is maintained in a [Git repository][repo-http], which can be cloned
from `git://git.proteanos.com/opkbuild/opkbuild.git`.
-[rel-ann]: http://lists.proteanos.com/proteanos-dev/2019/04/msg00001.html
+[rel-ann]: http://lists.proteanos.com/proteanos-dev/2020/07/msg00000.html
[dl-http]: http://files.proteanos.com/pub/opkbuild/
[dl-ftp]: ftp://files.proteanos.com/pub/opkbuild/
[repo-http]: http://git.proteanos.com/opkbuild/opkbuild.git/
diff --git a/dev/opkhelper.mdwn b/dev/opkhelper.mdwn
index 9d652c5..47bcd49 100644
--- a/dev/opkhelper.mdwn
+++ b/dev/opkhelper.mdwn
@@ -14,7 +14,7 @@ Debian.
Downloading
===========
-The current version of opkhelper is [3.1.2][rel-ann].
+The current version of opkhelper is [3.1.3][rel-ann].
opkhelper can be found on the ProteanOS files site by [HTTP][dl-http] or
[FTP][dl-ftp].
@@ -22,7 +22,7 @@ opkhelper can be found on the ProteanOS files site by [HTTP][dl-http] or
opkhelper is maintained in a [Git repository][repo-http], which can be cloned
from `git://git.proteanos.com/opkhelper/opkhelper.git`.
-[rel-ann]: http://lists.proteanos.com/proteanos-dev/2019/03/msg00003.html
+[rel-ann]: http://lists.proteanos.com/proteanos-dev/2020/07/msg00001.html
[dl-http]: http://files.proteanos.com/pub/opkhelper/
[dl-ftp]: ftp://files.proteanos.com/pub/opkhelper/
[repo-http]: http://git.proteanos.com/opkhelper/opkhelper.git/
diff --git a/dev/releases/1/packages.mdwn b/dev/releases/1/packages.mdwn
index 58bfcf0..02f6810 100644
--- a/dev/releases/1/packages.mdwn
+++ b/dev/releases/1/packages.mdwn
@@ -9,8 +9,9 @@ packages:
alsa-lib 1.0.27.2-1
alsa-utils 1.0.27.2-1
base-files 1.0.3
- bc 1.06.95-1
+ bc 1.07.1-1
binutils 2.32+sip1-1
+ bison 3.4.1-1
build-essential 1.2
busybox 1.21.1-13
bzip2 1.0.6-3
@@ -26,24 +27,27 @@ packages:
dev86 0.16.21-1
dropbear 2019.78-1
eglibc 2.19~r25243+sip1-3
- expat 2.1.0-2
+ expat 2.2.7-1
expect 5.45.4-1
- fakeroot 1.23-1
+ fakeroot 1.23-2
fbida 2.09-2
file 5.37-3
- flashrom 0.9.8~r1896-1
+ flashrom 1.1~rc1-1
+ flex 2.6.4-1
fontconfig 2.11.1-1
freetype 2.5.3-1
fss 1.0
- gawk 4.1.0-1
+ gawk 5.0.0-1
gcc-8 8.3.0+sip1-1
gcc-defaults 1.1
+ gdb 8.3+sip1-1
gettext 0.18.3.2-1
+ gettext-tiny 0.3.1
gmake 4.2.1-1
gmp 6.1.2-1
gnupg 2.2.15-1
gpgme 1.13.0-2
- ich9deblob 20150518fix~git20150628.0e3520f-1
+ ich9deblob 20160907-1
libarchive 3.1.2-1
libassuan 2.5.1-2
libexif 0.6.21-1
@@ -55,48 +59,53 @@ packages:
libnl-3 3.2.25-1
libogg 1.3.2-1
libpng12 1.2.51-2
- libsigsegv 2.10-1
+ libsigsegv 2.12-1
libtomcrypt 1.18.2-1
- libtommath.1 1.1.0-1
libtommath 0.42.0-1
+ libtommath.1 1.1.0-1
libtool 2.4.2-2
libubox 0+git20190227.eeef7b5-1
- libunistring 0.9.3-1
+ libunistring 0.9.10-1
libvorbis 1.3.4-1
lilo 24.2-1
linux-libre 3.10.60~gnu-1
- m4 1.4.17-2
+ m4 1.4.18-1
mpc 1.1.0-1
mpfr 4.0.2-1
mplus-fonts 058-2
- ncurses 5.9~20140301-2
+ ncurses 6.1+20190706-1
npth 1.6-1
+ nss-certdata 3.54-2
open-ath9k-htc-firmware 1.4~git20141115.146bff1-1
- opkbuild 4.0.2-1
+ opkbuild 4.2.0-1
opkg 0.2.4-3
opkg-lede 0+git20190131.d4ba162-6
- opkhelper-3.0 3.1.2-2
+ opkhelper-3.0 3.1.3-1
opkhelper-default 3.0.0
patch 2.7.6-1
- pciids 2019.06.07-1
+ pciids 2019.06.17-1
pciutils 3.6.2-1
pcre 8.35-1
pkgconf 0.9.6-1
- platconf-pkg-tools 2.1.1
+ platconf-pkg-tools 3.0.0
popt 1.16+sip1-1
+ proquivs 1.0
proteanos-branding 0.3
pth 2.0.7-1
readline 6.3-1
+ readline.8 8.0-1
strace 4.8-1
tcl8.6 8.6.9+sip1-2
tzdb 2019a-1
usign 0+git20161022.3e6648b-1
+ wolfssl.24 4.4.0-3
+ wolfutil 1.0.0-2
wpa-supplicant 2.2-2
xz 5.2.4-1
zlib 1.2.11+sip1-1
------------------------------------------------------------
- Source packages: 89
- Binary packages: 354
+ Source packages: 98
+ Binary packages: 395
The above list was generated by running the following shell script:
@@ -106,9 +115,6 @@ The above list was generated by running the following shell script:
verw=33
base_url='http://files.proteanos.com/pub/proteanos/feeds/dev/trunk'
- LF='
- '
-
# Print header
i=0
l=$(($pkgw + $verw + 2))
@@ -133,17 +139,18 @@ The above list was generated by running the following shell script:
;;
esac
done <<EOF
- $(wget -q -O - "${base_url}/src/all/base/Packages")
+ $(wget -q -O - "${base_url}/src/all/base/Packages" \
+ "${base_url}/src/all/src/Packages")
EOF
# Collect binary package names
bins=''
- for aps in $(wget -q -O - "${base_url}/Manifest" | grep -Fv 'src/all/base'); do
- bins="${bins}${LF}$(wget -q -O - "${base_url}/${aps}/Packages" | \
+ for aps in $(wget -q -O - "${base_url}/Manifest" | grep -Fv 'src/all/'); do
+ bins="${bins} $(wget -q -O - "${base_url}/${aps}/Packages" | \
sed -n 's/^Package: //p;')"
done
# Print totals
printf '%s\n' "${tblline}"
printf 'Source packages: %d\n' "${srcs}"
- printf 'Binary packages: %d\n' "$(printf '%s\n' "${bins}" | sort -u | wc -l)"
+ printf 'Binary packages: %d\n' "$(printf '%s\n' ${bins} | sort -u | wc -l)"
diff --git a/dev/todo/install-bb-without-bb.mdwn b/dev/todo/install-bb-without-bb.mdwn
new file mode 100644
index 0000000..4bb90ff
--- /dev/null
+++ b/dev/todo/install-bb-without-bb.mdwn
@@ -0,0 +1,86 @@
+[[!meta title="Installing BusyBox Without BusyBox"]]
+
+**or, Adventures in Regressions and Crazy Ideas**
+
+---
+
+**This work is now done.**
+
+**The rest of this page is kept only for reference and historical purposes.**
+
+---
+
+Two Problems
+============
+
+`opkg-lede` and the Outsourced Inflation
+----------------------------------------
+
+`opkg-lede` [now relies][opkg-lede-dd4c78a] on an external `gzip` executable.
+When upgrading a package, it tries to execute `gzip` to unpack maintainer
+scripts and data files [after removing][opkg_install_pkg] the old version of the
+package. When the package being upgraded is `busybox`, which provides `gzip`,
+`opkg` crashes and leaves behind a completely broken system.
+
+To reiterate, `opkg-lede` is (and has been for as long as it has been in
+ProteanOS) **currently unable to upgrade `busybox`**, due to its own design.
+
+[opkg-lede-dd4c78a]: https://git.openwrt.org/?p=project/opkg-lede.git;a=commitdiff;h=dd4c78aa88efd3b9cf516030937c684814df7962
+[opkg_install_pkg]: https://git.openwrt.org/?p=project/opkg-lede.git;a=blob;f=libopkg/opkg_install.c;hb=d4ba162#l1520
+
+The Amazing Alternatives of `busybox`
+-------------------------------------
+
+Instead of [adding alternatives][alts-log] one at a time, [it would be
+nice][bb-ua] to manage all of `busybox`'s utility links using
+`update-alternatives`. Unfortunately, the [maintainer script][bb.pi] that runs
+`update-alternatives` (as well as the [`update-alternatives` script][u-a]
+itself) needs a few `busybox` utilities (`/bin/sh` for a start). Thus, after an
+older version of `busybox` is deconfigured, a newer version can't be configured.
+`busybox` also can't be configured when first unpacked by `prokit`.
+
+[alts-log]: http://git.proteanos.com/pkg/busybox.git/log/alternatives
+[bb-ua]: http://git.proteanos.com/pkg/busybox.git/commit/?id=1558d05c62ed90f7d93a14533541c33896b7b733
+[bb.pi]: http://git.proteanos.com/pkg/busybox.git/tree/busybox.pkg/postinst
+[u-a]: https://git.openwrt.org/?p=project/opkg-lede.git;a=blob;f=utils/update-alternatives.in;hb=d4ba162
+
+One Solution
+============
+
+The next version of `src:opkg-lede` (likely 0+git20190131.d4ba162-7) already
+will have a [wrapper script called `opkg`][opkg] that executes `opkg-cl` (the
+actual binary executable). The script can be extended to first save a copy of
+`/bin/busybox` to an empty temporary directory, generate utility links to it in
+the directory, and add the directory to `PATH`. Until all of this setup is
+complete, the wrapper script must be careful to execute utilities as `busybox
+$util` (a full path to `busybox` won't be necessary, as the usual `/bin/busybox`
+will be available at that point). This includes the interpreter line, which
+will need to be changed to `#!/bin/busybox sh`. `ash` built-in utilities can be
+used as usual.
+
+The `busybox` package can't use `update-alternatives` to manage all of its
+utility links until an `opkg-lede` with this wrapper script functionality is
+uploaded. This is because, even if `busybox`'s `postinst` script is modified to
+use the `busybox` executable directly, other packages' maintainer scripts may be
+executed first, while `busybox` is unpacked but not yet configured (and
+therefore utility links are not yet created).
+
+Once this new `opkg-lede` package is uploaded and `busybox` uses
+`update-alternatives` for everything, `busybox` would need to declare that it
+`Breaks` older versions of `opkg-lede`, to ensure that `opkg-lede` will preserve
+a copy of the `busybox` executable and its utility links. However, this is
+still insufficient, as the version of `opkg` that is *running* must have already
+set up this environment before `busybox` is upgraded. `busybox`'s `prerm`
+script will need to check for this somehow and abort the upgrade if `opkg` is
+too old to have prepared for a safe upgrade. One solution is for the `opkg`
+script to set an `OPKG_BUSYBOX_SAVED` environment variable.
+
+The `opkg` script of the `opkg-lede` package will need to read `busybox`'s list
+of alternatives links. This is currently located at
+`/usr/share/busybox/alternatives`. [The file's format][alts] will change when
+`busybox` uses `update-alternatives` for everything: the last two columns (name
+and priority) will be dropped. `opkg` however can simply read the first column,
+so it will maintain compatibility.
+
+[opkg]: http://git.proteanos.com/pkg/opkg-lede.git/tree/opkg
+[alts]: http://git.proteanos.com/pkg/busybox.git/tree/alternatives?id=e37f03311d934a8f33a9ff31db47b18bbf0be555
diff --git a/dev/wolfutil.mdwn b/dev/wolfutil.mdwn
new file mode 100644
index 0000000..1fba2fe
--- /dev/null
+++ b/dev/wolfutil.mdwn
@@ -0,0 +1,48 @@
+[[!meta title="Unofficial wolfSSL Utility"]]
+
+wolfutil is a command-line tool for the wolfSSL embedded (SSL/)TLS
+library. It is similar to the OpenSSL command-line tool, providing only
+a limited `s_client` TLS client command. The primary goal is to provide
+enough functionality for use by BusyBox's wget applet.
+
+wolfutil's `s_client` command is designed to be stronger by default than
+OpenSSL's, as the latter is only meant to be a "diagnostic tool". That
+is, the following command:
+
+ $ wolfutil s_client -quiet -connect ${host}:${port} \
+ > -servername ${servername}
+
+is roughly equivalent to the more complicated:
+
+ $ openssl s_client -quiet -connect ${host}:${port} \
+ > -servername ${servername} -verify 9 -verify_return_error \
+ > -no_ssl3 -no_tls1 -no_tls1_1
+
+This utility is in no way authored by or affiliated with wolfSSL Inc. or
+its contributors.
+
+
+Downloading
+===========
+
+The current version of wolfutil is [1.0.0][rel-ann].
+
+wolfutil can be found on the ProteanOS files site by [HTTP][dl-http] or
+[FTP][dl-ftp].
+
+wolfutil is maintained in a [Git repository][repo-http], which can be cloned
+from `git://git.proteanos.com/wolfutil/wolfutil.git`.
+
+[rel-ann]: http://lists.proteanos.com/proteanos-dev/2020/08/msg00000.html
+[dl-http]: http://files.proteanos.com/pub/wolfutil/
+[dl-ftp]: ftp://files.proteanos.com/pub/wolfutil/
+[repo-http]: http://git.proteanos.com/wolfutil/wolfutil.git/
+
+
+Mailing List
+============
+
+Bug reports, feature requests, and patches for wolfutil are welcome on the
+[ProteanOS development mailing list][proteanos-dev].
+
+[proteanos-dev]: http://lists.proteanos.com/proteanos-dev/
diff --git a/doc/install.mdwn b/doc/install.mdwn
index 533040b..11b364a 100644
--- a/doc/install.mdwn
+++ b/doc/install.mdwn
@@ -8,9 +8,15 @@ install and manage ProteanOS systems. [[Get_started!_→|doc/install/prokit]]
Then, choose how and where to install ProteanOS:
- * [[In_an_isolated_file_system_environment_→|doc/install/chroot]]
+ * [[On_an_existing_host_system_under_an_isolated_file_system_environment_→|doc/install/chroot]]
* [[On_a_supported_PC_→|doc/install/pc]]
+ProteanOS package development is typically done on an different host system.
+Running ProteanOS on actual hardware is only necessary for testing things like
+hardware-specific features (e.g. booting with a new `linux-image-*` package),
+network configuration, or system services (e.g. a logging daemon or a Web
+server).
+
See the [[legal_and_technical_notices|doc/legal]] to learn how to find copyright
information for ProteanOS packages and how to build ProteanOS packages from
source code.
diff --git a/doc/install/chroot.mdwn b/doc/install/chroot.mdwn
index cc4a86c..0b27ffe 100644
--- a/doc/install/chroot.mdwn
+++ b/doc/install/chroot.mdwn
@@ -14,19 +14,21 @@ It is assumed that you have already
Installing ProteanOS
====================
-First decide which "suite" of ProteanOS you wish to install. Currently only one
-suite is available: `dev/trunk`.
+First decide which "suite" of ProteanOS you wish to install. `rel/trunk` is a
+rolling release that receives updates free of known new bugs; it is recommended
+for regular users. `dev/trunk` receives direct package uploads and should be
+used by ProteanOS developers. Replace `$suite` below with your chosen suite.
Next decide where to install ProteanOS. Replace `$root` below with the path to
which you want ProteanOS installed.
If you installed prokit to your system, simply run:
- $ sudo prokit install dev/trunk $root
+ $ sudo prokit install $suite $root
Otherwise, from your prokit build directory, run:
- $ sudo ./prokit install dev/trunk $root
+ $ sudo ./prokit install $suite $root
Next Steps
==========
diff --git a/doc/install/pc.mdwn b/doc/install/pc.mdwn
index dd421d5..663a05c 100644
--- a/doc/install/pc.mdwn
+++ b/doc/install/pc.mdwn
@@ -17,9 +17,6 @@ Make sure you have a computer supported by ProteanOS. If your computer is not
supported, you can [[port_ProteanOS_to_run_on_it|doc/plat/porting]]. Currently
supported are:
- * Acer Aspire One AO751h (architecture `i686-linux-glibc`, platform `ao751h`)
- * Dell Dimension 2400 (architecture `i686-linux-glibc`, platform
- `dimension2400`)
* Lenovo ThinkPad X60, X60s, X60t, T60 (architecture `i686-linux-glibc`,
platform `x60`)
* Lenovo ThinkPad X200, X200s, X200 Tablet, R400, T400, R500, T500, etc.
@@ -27,10 +24,8 @@ supported are:
* Libiquity Taurinus X200 and Gluglug Libreboot X200 (architecture
`i686-linux-glibc`, platform `x60`)
-Determine the devices from which your computer can boot. For example, the Acer
-Aspire One AO751h can boot from an internal 2.5" SATA drive or from a storage
-device connected over USB (e.g. a flash drive), while the Dell Dimension 2400
-can only boot from an internal PATA drive.
+Determine the devices from which your computer can boot, for example an internal
+SATA drive or a USB mass storage device (e.g. a flash drive).
Pick a storage device on which you want to install ProteanOS and connect it to
the computer on which you plan to run the installer. You can either connect the
@@ -42,13 +37,18 @@ system on the computer on which you plan to install ProteanOS.
Installation
============
+Decide which "suite" of ProteanOS you wish to install. `rel/trunk` is a rolling
+release that receives updates free of known new bugs; it is recommended for
+regular users. `dev/trunk` receives direct package uploads and should be used
+by ProteanOS developers. Replace `$suite` below with your chosen suite.
+
If you installed prokit to your system, run:
- $ sudo prokit installer-pc -a $arch -p $plat dev/trunk $device
+ $ sudo prokit installer-pc -a $arch -p $plat $suite $device
Otherwise, from your prokit build directory, run:
- $ sudo ./prokit installer-pc -a $arch -p $plat dev/trunk $device
+ $ sudo ./prokit installer-pc -a $arch -p $plat $suite $device
Replace `$arch` with the architecture (e.g. `i686-linux-glibc`), `$plat` with
the platform (e.g. `x60`), and `$device` with the device file name (e.g.
diff --git a/doc/install/prokit.mdwn b/doc/install/prokit.mdwn
index 55def93..828075c 100644
--- a/doc/install/prokit.mdwn
+++ b/doc/install/prokit.mdwn
@@ -8,45 +8,75 @@ to install a ProteanOS system, run a ProteanOS shell and other commands, manage
software packages on an installed ProteanOS system, and build packages for
ProteanOS.
-prokit requires gunzip, either sfdisk or fdisk, mke2fs, cpio, and xz from XZ
-Utils; the `configure` script should find these automatically if installed.
-prokit also requires OpenWrt's usign utility to verify archive signatures. An
-embedded copy of usign is included, building of which additionally requires
-CMake, a **make**(1) utility such as GNU Make, a C compiler such as GCC, and
-standard C library headers (`sudo apt-get install build-essential cmake` is
-sufficient on a Debian-based distribution such as Trisquel); or a system copy of
-usign can be used instead.
+
+Dependencies
+============
+
+Building prokit requires make, a POSIX-conformant shell with `local`, and basic
+standard utilities. Git and GNU Autoconf and Automake are currently also
+required.
+
+Running prokit requires the following utilities:
+
+ * A POSIX-conformant shell with `local` and standard utilities
+ * gunzip
+ * Either sfdisk or fdisk
+ * mke2fs
+ * cpio
+ * xz from XZ Utils
+ * mount
+ * umount
+ * chroot
+
+prokit also requires OpenWrt's usign utility to verify archive signatures. A
+system copy of usign can be used, however few distributions provide one. An
+embedded copy of usign is included, building of which additionally requires:
+
+ * CMake
+ * A C compiler such as GCC and standard C library headers
+
+On a Debian-based distribution such as Trisquel, `sudo apt-get install
+build-essential cmake` is sufficient.
To install and manage ProteanOS systems you need a host system running Linux 3.4
or later.
-The ProteanOS Development Kit uses the **chroot**(8) and **mount**(8) commands,
-which on Linux require superuser access. This guide assumes the use of
-**sudo**(8) for running commands with superuser privileges. Adjust where
-necessary if you don't use **sudo**(8).
+The ProteanOS Development Kit uses the **mount**(8) , **umount**(8), and
+**chroot**(8) commands, which on Linux require superuser access. This guide
+assumes the use of **sudo**(8) for running commands with superuser privileges.
+Adjust where necessary if you don't use **sudo**(8).
Downloading the ProteanOS Development Kit
=========================================
-Download a released version of prokit from the files site by [HTTP][prokit-http]
-or [FTP][prokit-ftp], e.g.:
+prokit release archives since version 1.1.0 and Git commits since
+2.0.1-55-g545e082 are signed with the maintainer's OpenPGP 4096-bit RSA key.
+Import the key from a key server (available on the SKS network and on
+keys.openpgp.org). Finding a signature path from trusted keys in your keyring
+to this key is recommended if possible.
$ gpg --recv-keys 0x225031F047FFE51663ED516F1A459ECDE4D604BE
- $ # Find a signature path from your keyring to 0x1A459ECDE4D604BE
- $ wget http://files.proteanos.com/pub/prokit/2.0.0/prokit-2.0.0.tar.gz \
- > http://files.proteanos.com/pub/prokit/2.0.0/prokit-2.0.0.tar.gz.asc
- $ gpg --verify prokit-2.0.0.tar.gz.asc prokit-2.0.0.tar.gz
- $ tar -xzf prokit-2.0.0.tar.gz
- $ cd prokit-2.0.0/
-Or clone prokit from the [Git repository][prokit-git]:
+The current released version (2.0.1) of prokit lacks features now used by the
+ProteanOS package archive. Clone prokit from the [Git repository][prokit-git]:
$ git clone git://git.proteanos.com/prokit/prokit.git
$ cd prokit/
-[prokit-http]: http://files.proteanos.com/pub/prokit/
-[prokit-ftp]: ftp://files.proteanos.com/pub/prokit/
+Check for signatures on the recent commits. Either run:
+
+ $ git log --show-signature
+
+Or configure Git to always show signatures in the log (requires Git 2.10 or
+later):
+
+ $ git config log.showSignature true
+ $ git log
+
+Either way, look for a `Good signature` made `using RSA key
+225031F047FFE51663ED516F1A459ECDE4D604BE` in at least the top-most commits.
+
[prokit-git]: http://git.proteanos.com/prokit/prokit.git/
@@ -55,17 +85,9 @@ Building the ProteanOS Development Kit
Configure and build prokit:
- $ ./configure
- $ make
-
-Or, if you cloned the Git repository, run:
-
$ ./autogen.sh
$ make
-To build from the repository you'll need to have GNU Autoconf and Automake
-installed.
-
Installing the ProteanOS Development Kit
========================================
diff --git a/templates/page.tmpl b/templates/page.tmpl
index 5370e18..ddb0e9e 100644
--- a/templates/page.tmpl
+++ b/templates/page.tmpl
@@ -164,12 +164,12 @@
<!-- Created <TMPL_VAR CTIME> -->
</p>
<p class="copyright">
- Copyright &copy; 2011–2017
+ Copyright &copy; 2011–2020
Patrick M<span class="super">c</span>Dermott
</p>
<p class="copyright">
ProteanOS is sponsored by
- <a href="http://libiquity.com/">Libiquity</a>.
+ <a href="https://www.libiquity.com/">Libiquity</a>.
</p>
</div>
</footer>