diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/install.mdwn | 8 | ||||
| -rw-r--r-- | doc/install/chroot.mdwn | 47 | ||||
| -rw-r--r-- | doc/install/jail.mdwn | 44 | ||||
| -rw-r--r-- | doc/install/pc.mdwn | 22 | ||||
| -rw-r--r-- | doc/install/prokit.mdwn | 81 | ||||
| -rw-r--r-- | doc/plat/porting.mdwn | 74 |
6 files changed, 153 insertions, 123 deletions
diff --git a/doc/install.mdwn b/doc/install.mdwn index 45b9c8d..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/jail]] + * [[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 new file mode 100644 index 0000000..0b27ffe --- /dev/null +++ b/doc/install/chroot.mdwn @@ -0,0 +1,47 @@ +[[!meta title="Isolated File System Environment Installation"]] + +[[←_Back_to_Installing_ProteanOS|doc/install]] + +These instructions explain how to install ProteanOS into a directory on an +existing host system to run under an isolated file system environment, or +"jail", using prokit, the ProteanOS Development Kit. prokit will run ProteanOS +using the **chroot**(2) system call via the **chroot**(8) wrapper program. + +It is assumed that you have already +[[built_and_optionally_installed_prokit|doc/install/prokit]]. + + +Installing ProteanOS +==================== + +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 $suite $root + +Otherwise, from your prokit build directory, run: + + $ sudo ./prokit install $suite $root + +Next Steps +========== + +Familiarize yourself with the ProteanOS Development Kit Manual, if you haven't +already. The **prokit-shell**(8) and **prokit-opkg**(8) commands are used to +manage installed ProteanOS systems. + +If you'd like to develop packages for ProteanOS, you need to install the +`build-essential` package (again replacing `prokit` with `./prokit` if you +haven't installed prokit): + + $ sudo prokit opkg $root install build-essential + +This may take a while, depending on your network connection. Then you can start +[[learning_how_to_prepare_packages|doc/pkg]]! diff --git a/doc/install/jail.mdwn b/doc/install/jail.mdwn index 35020b0..1a07fd1 100644 --- a/doc/install/jail.mdwn +++ b/doc/install/jail.mdwn @@ -1,45 +1,3 @@ [[!meta title="Isolated File System Environment Installation"]] -[[←_Back_to_Installing_ProteanOS|doc/install]] - -These instructions explain how to install ProteanOS into a directory on an -existing host system to run under an isolated file system environment, or -"jail", using prokit, the ProteanOS Development Kit. prokit will run ProteanOS -using the **chroot**(2) system call via the **chroot**(8) wrapper program. - -It is assumed that you have already -[[built_and_optionally_installed_prokit|doc/install/prokit]]. - - -Installing ProteanOS -==================== - -First decide which "suite" of ProteanOS you wish to install. Currently only one -suite is available: `dev/trunk`. - -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 - -Otherwise, from your prokit build directory, run: - - $ sudo src/prokit install dev/trunk $root - -Next Steps -========== - -Familiarize yourself with the ProteanOS Development Kit Manual, if you haven't -already. The **prokit-shell**(8) and **prokit-opkg**(8) commands are used to -manage installed ProteanOS systems. - -If you'd like to develop packages for ProteanOS, you need to install the -`build-essential` package (again replacing `prokit` with `src/prokit` if you -haven't installed prokit): - - $ sudo prokit opkg $root install build-essential - -This may take a while, depending on your network connection. Then you can start -[[learning_how_to_prepare_packages|doc/pkg]]! +Moved to [[doc/install/chroot]]. diff --git a/doc/install/pc.mdwn b/doc/install/pc.mdwn index 619ab60..663a05c 100644 --- a/doc/install/pc.mdwn +++ b/doc/install/pc.mdwn @@ -2,10 +2,6 @@ [[←_Back_to_Installing_ProteanOS|doc/install]] -**NOTE:** These instructions use a feature in an unreleased version of the -ProteanOS Development Kit. You'll need to have built prokit from its Git -repository to use the PC installer. - This guide explains how to use the interactive installer program distributed with prokit, the ProteanOS Development Kit, to install ProteanOS on a PC platform. @@ -21,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. @@ -31,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 @@ -46,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 src/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 3e32017..828075c 100644 --- a/doc/install/prokit.mdwn +++ b/doc/install/prokit.mdwn @@ -8,40 +8,76 @@ 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. -Building and installing prokit is easy. Ensure you have a **make**(1) utility -such as GNU Make installed. No C or C++ compiler or other development tools are -necessary to build prokit. 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). +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 **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 ========================================= -Clone prokit from the [Git repository][prokit-git]: +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 + +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/ -*(Using the current released version, 1.1.0, is not recommended at this time, as -the Git repository contains numerous major [improvements][prokit-news] including -use of an updated mirrors list and installer commands for PC block devices and -initramfs images. The head of the Git master branch is stable, with no known -bugs. Version 2.0.0 will be released soon, pending some additional new -features.)* +Check for signatures on the recent commits. Either run: + + $ git log --show-signature -Users of Parabola GNU/Linux-libre and Arch [GNU/]Linux can find prokit packages -in the AUR (thanks to Serge Victor): +Or configure Git to always show signatures in the log (requires Git 2.10 or +later): - * [prokit-git][aur-prokit-git] + $ 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/ -[prokit-news]: http://git.proteanos.com/prokit/prokit.git/tree/NEWS/ -[aur-prokit-git]: https://aur.archlinux.org/packages/prokit-git/ Building the ProteanOS Development Kit @@ -52,9 +88,6 @@ Configure and build prokit: $ ./autogen.sh $ make -To build from the repository you'll need to have GNU Autoconf and Automake -installed. - Installing the ProteanOS Development Kit ======================================== @@ -78,3 +111,5 @@ prokit comes with a manual, starting with the **prokit**(1) page: Or, if you didn't install prokit, you can find the manual by running: $ man man/prokit.1 + +The manual is also available from the [[prokit_homepage|dev/prokit]]. diff --git a/doc/plat/porting.mdwn b/doc/plat/porting.mdwn index fe83706..c9d0e5d 100644 --- a/doc/plat/porting.mdwn +++ b/doc/plat/porting.mdwn @@ -16,23 +16,15 @@ So read on to port ProteanOS to your computer! Set Up a ProteanOS System ========================= -Get miniprokit, the "Mini ProteanOS Development Kit", as instructed on the -[[download_page|get]]. +[[Get_prokit|doc/install/prokit]], the ProteanOS Development Kit. -Connect the storage medium (e.g. a hard disk drive connected using a USB -adapter/dock or a USB flash drive). On it, create one primary partition of type -0x83 (Linux) and mark it as bootable. cfdisk, sfdisk, or fdisk can be used for -this. +Connect a storage medium (e.g. a hard disk drive connected using a USB +adapter/dock or a USB flash drive). Run the following commands (replacing +`/dev/sdb` with the path to storage device and `i686-linux-glibc` with the +architecture of the target system) to create a partition layout and file system +and install ProteanOS into it: -Run the following commands (replacing `/dev/sdc1` with the path to the newly -created partition and `i686-linux-glibc` with the architecture of the target -system) to make and mount an ext4 file system, install ProteanOS into it, and -enter a ProteanOS shell: - - # mke2fs -t ext4 /dev/sdc1 - # mount /dev/sdc1 /mnt - # /path/to/miniprokit.sh install -a i686-linux-glibc -P dev /mnt - # /path/to/miniprokit.sh shell /mnt + # prokit installer-pc -a i686-linux-glibc -p dev dev/trunk /dev/sdb Install, Configure, and Build the `linux-libre` Source Package @@ -43,31 +35,32 @@ Choose a platform on which this new platform will be based. In this tutorial, Install toolchain packages, the source package, and build dependencies: - / # opkg install build-essential-$(cat /etc/proteanos_arch) \ - > src-linux-libre config-linux-libre-ao751h bc xz \ - > libncursesw.5-dev libtinfo-dev terminfo + # prokit opkg /dev/sdb1 install build-essential src-linux-libre \ + > config-linux-libre-ao751h bc xz libncursesw.5-dev libtinfo-dev terminfo -Change to the source package directory and use opkbuild to unpack the upstream -sources and install platform configuration files: +Start a ProteanOS shell, change to the source package directory, and use +opkbuild to unpack the upstream sources and install platform configuration +files: - / # cd /usr/src/linux-libre_3.10.40~gnu-2/ - /usr/src/linux-libre_3.10.40~gnu-2 # opkbuild -bcT nop -P ao751h + # prokit shell /dev/sdb1 + # cd /usr/src/linux-libre_*/ + # opkbuild -bcT nop -p ao751h Hide the list of platform configuration files from opkbuild, so the modified configuration won't get overwritten: - /usr/src/linux-libre_3.10.40~gnu-2 # mv platconf platconf.no + # mv platconf platconf.no Enter the upstream source tree and configure Linux-libre: - /usr/src/linux-libre_3.10.40~gnu-2 # cd tmp/src/ - /usr/src/linux-libre_3.10.40~gnu-2/tmp/src # make menuconfig + # cd tmp/src/ + # make menuconfig Return to the source package directory and build the package for a platform other than `dev`: - /usr/src/linux-libre_3.10.40~gnu-2/tmp/src # cd ../../ - /usr/src/linux-libre_3.10.40~gnu-2 # opkbuild -bcdP dimension2400 + # cd ../../ + # opkbuild -bcdp dimension2400 Make the System Bootable @@ -75,22 +68,16 @@ Make the System Bootable Install the newly built linux-image package: - /usr/src/linux-libre_3.10.40~gnu-2 # opkg install \ - > ../linux-image_3.10.40~gnu-2_i686-linux-glibc_dimension2400.opk + # opkg install ../linux-image_*_i686-linux-glibc_dimension2400.opk Set a hostname and enable initialization of services: - /usr/src/linux-libre_3.10.40~gnu-2 # cd / - / # printf 'proteanos\n' >/etc/hostname - / # printf 'enabled\n' >/etc/rc.policy + # printf 'proteanos\n' >/etc/hostname + # printf 'enabled\n' >/etc/rc.policy Exit the ProteanOS shell: - / # exit - -Back on the host system, unmount the file system: - - # umount /mnt + # exit The storage medium can then be removed and connected to the target computer. @@ -104,8 +91,8 @@ Once the `linux-libre` configuration is tested to boot and support all the relevant hardware and features, a configuration package should be made. Download the `config-*` package for the base platform you chose, either by -running, for example, `opkg install src-config-ao751h` on ProteanOS or by -cloning the relevant Git repository, e.g. `git clone +running, for example, `prokit opkg install src-config-ao751h` or by cloning the +relevant Git repository, e.g. `git clone git://git.proteanos.com/pkg/config-ao751h.git`. Set the `Maintainer` field in the `control` file. @@ -125,8 +112,9 @@ Regenerate the metadata for the binary packages: $ ./config Copy the `linux-libre` configuration file (`tmp/src/.config` under the source -package directory) into `src/linux-libre/*/`. +package directory) into `src/linux-libre/*/` in your new configuration source +package. -The `config-*` package can then be built, e.g. `opkbuild -S` to build the source -package. Please notify the ProteanOS community of your porting work, if you -haven't already, and offer to upload and maintain the `config-*` package. +Your configuration package can then be built, e.g. `prokit build -S .` to build +the source package. Please notify the ProteanOS community of your porting work, +if you haven't already, and offer to upload and maintain the `config-*` package. |