diff options
| -rw-r--r-- | dev/releases/1/packages.mdwn | 2 | ||||
| -rw-r--r-- | dev/todo/install-bb-without-bb.mdwn | 86 | ||||
| -rw-r--r-- | doc/install.mdwn | 8 | ||||
| -rw-r--r-- | doc/install/chroot.mdwn | 10 | ||||
| -rw-r--r-- | doc/install/pc.mdwn | 18 | ||||
| -rw-r--r-- | doc/install/prokit.mdwn | 84 |
6 files changed, 162 insertions, 46 deletions
diff --git a/dev/releases/1/packages.mdwn b/dev/releases/1/packages.mdwn index cbc55e1..02f6810 100644 --- a/dev/releases/1/packages.mdwn +++ b/dev/releases/1/packages.mdwn @@ -99,7 +99,7 @@ packages: tzdb 2019a-1 usign 0+git20161022.3e6648b-1 wolfssl.24 4.4.0-3 - wolfutil 1.0.0-1 + wolfutil 1.0.0-2 wpa-supplicant 2.2-2 xz 5.2.4-1 zlib 1.2.11+sip1-1 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/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 ======================================== |