doc/legal: New page

2 files changed, 178 insertions, 0 deletions

diff --git a/doc/install.mdwn b/doc/install.mdwn
index a885c27..8016673 100644
--- a/doc/install.mdwn
+++ b/doc/install.mdwn
@@ -9,3 +9,7 @@ Then, choose how and where to install ProteanOS:
 
   * [[In_an_isolated_file_system_environment_→|doc/install/jail]]
   * [[On_a_PC_→|doc/install/pc]]
+
+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/legal.mdwn b/doc/legal.mdwn
new file mode 100644
index 0000000..7fa60d9
--- /dev/null
+++ b/doc/legal.mdwn
@@ -0,0 +1,174 @@
+[[!meta title="Legal and Technical Notices"]]
+
+Copyright Information
+=====================
+
+The programs included with ProteanOS are free software; the exact distribution
+terms for each program are described in the individual files in
+`/usr/share/doc/*/copyright` on a ProteanOS system.
+
+
+Getting and Building ProteanOS Source Code
+==========================================
+
+ProteanOS's binary packages are built from source packages, which can be
+installed and built on a ProteanOS system.
+
+Getting a Source Package
+------------------------
+
+First pick a source package you want to download.  If you're not sure which
+source package builds a particular binary package, you can use the **opkg**
+utility to check the package's `Source` control field.  From a ProteanOS shell,
+run the following command:
+
+    # opkg info file | grep '^Source: '
+    Source: file
+
+Or using prokit, run the following, where `$root` is the path to your ProteanOS
+system's root:
+
+    $ sudo prokit opkg $root info file | grep '^Source: '
+    Source: file
+
+This tells us that the `file` source package builds the `file` binary package.
+Now, install `src-<srcpkg>`.  From ProteanOS:
+
+    # opkg install src-file
+    Installing src-file (5.17-3) to root...
+    Downloading http://us.mirror.gnu.dk/pub/proteanos/feeds/dev/trunk/src/all/base/../../../../../../pool/f/file/src-file_5.17-3_src_all.opk.
+    Configuring src-file.
+
+Or using prokit:
+
+    $ sudo prokit opkg $root install src-file
+    Installing src-file (5.17-3) to root...
+    Downloading http://us.mirror.gnu.dk/pub/proteanos/feeds/dev/trunk/src/all/base/../../../../../../pool/f/file/src-file_5.17-3_src_all.opk.
+    Configuring src-file.
+
+Find the source package installed under `/usr/src/`:
+
+    # ls /usr/src/file_5.17-3/
+    build                  file-doc.pkg           libmagic.1.pkg
+    changelog              file.pkg               source.mk
+    control                format                 substvars
+    copyright              libmagic-dev.pkg
+    file-5.17.orig.tar.gz  libmagic-doc.pkg
+
+Or:
+
+    $ sudo prokit shell $root ls /usr/src/file_5.17-3/
+    build                  file-doc.pkg           libmagic.1.pkg
+    changelog              file.pkg               source.mk
+    control                format                 substvars
+    copyright              libmagic-dev.pkg
+    file-5.17.orig.tar.gz  libmagic-doc.pkg
+
+Building the Source Package
+---------------------------
+
+First, install the `build-essential` binary package if you haven't already:
+
+    # opkg install build-essential
+
+Or:
+
+    $ sudo prokit opkg $root install build-essential
+
+If you're using a ProteanOS shell directly, you'll have to manually find and
+install the build dependencies.  Check the `control` file:
+
+    # cd /usr/src/file_5.17-3/
+    # cat control
+    Maintainer: "P. J. McDermott" <pj@pehjota.net>
+    Build-Depends: opkhelper-3.0, libz.1-dev
+    Homepage: http://www.darwinsys.com/file/
+
+This source package needs the `opkhelper-3.0` and `libz.1-dev` packages to
+build.  Install those:
+
+    # opkg install opkhelper-3.0 libz.1-dev
+    Package opkhelper-3.0 (3.0.0-2) installed in root is up to date.
+    Installing libz.1-dev (1.2.8+sip1-1) to root...
+    Downloading http://us.mirror.gnu.dk/pub/proteanos/feeds/dev/trunk/amd64-linux-glibc/all/base/../../../../../../pool/z/zlib/libz.1-dev_1.2.8+sip1-1_amd64-linux-glibc_all.opk.
+    Configuring libz.1-dev.
+
+Finally, run **opkbuild** to build the package:
+
+    # opkbuild
+    opkbuild: Detecting architecture and platform...
+    opkbuild: Making work area...
+    opkbuild: Parsing package metadata...
+    opkbuild: Building source package...
+    ob-genchanges: Generating "file_5.17-3_src_all.changes"...
+    opkbuild: Build system:
+    opkbuild:   Architecture:  amd64-linux-glibc
+    opkbuild:   Platform:      dev
+    opkbuild: Host system:
+    opkbuild:   Architecture:  amd64-linux-glibc
+    opkbuild:   Platform:      dev
+    [...]
+    ob-installdocs: Making link to documentation in package "file"...
+    ob-installdocs: Making link to documentation in package "libmagic-dev"...
+    ob-installdocs: Installing package documentation into package "libmagic.1"...
+    ob-installdocs: Making link to documentation in package "file-doc"...
+    ob-installdocs: Making link to documentation in package "libmagic-doc"...
+    ob-genchanges: Generating "file_5.17-3_amd64-linux-glibc_dev.changes"...
+
+Or if you're using prokit, you can simply run the following command, and prokit
+will find and install the build dependencies automatically:
+
+    $ sudo prokit build $root $root/usr/src/file_5.17-3/
+    Installing prokit-builddeps-1521897985 (1.0) on root.
+    Package opkhelper-3.0 (3.0.0-2) installed in root is up to date.
+    Installing libz.1-dev (1.2.8+sip1-1) on root.
+    Downloading http://us.mirror.gnu.dk/pub/proteanos/feeds/dev/trunk/amd64-linux-glibc/all/base/../../../../../../pool/z/zlib/libz.1-dev_1.2.8+sip1-1_amd64-linux-glibc_all.opk.
+    Configuring libz.1-dev.
+    Configuring prokit-builddeps-1521897985.
+    opkbuild: Detecting architecture and platform...
+    opkbuild: Making work area...
+    opkbuild: Parsing package metadata...
+    opkbuild: Building source package...
+    ob-genchanges: Generating "file_5.17-3_src_all.changes"...
+    opkbuild: Build system:
+    opkbuild:   Architecture:  amd64-linux-glibc
+    opkbuild:   Platform:      dev
+    opkbuild: Host system:
+    opkbuild:   Architecture:  amd64-linux-glibc
+    opkbuild:   Platform:      dev
+    [...]
+    ob-installdocs: Making link to documentation in package "file"...
+    ob-installdocs: Making link to documentation in package "libmagic-dev"...
+    ob-installdocs: Installing package documentation into package "libmagic.1"...
+    ob-installdocs: Making link to documentation in package "file-doc"...
+    ob-installdocs: Making link to documentation in package "libmagic-doc"...
+    ob-genchanges: Generating "file_5.17-3_amd64-linux-glibc_dev.changes"...
+    Removing package prokit-builddeps-1521897985 from root...
+    libz.1-dev was autoinstalled and is now orphaned, removing.
+    Removing package libz.1-dev from root...
+
+Find the resulting packages and changes files in `/usr/src/`:
+
+    # ls /usr/src/
+    file-doc_5.17-3_all_all.opk
+    file_5.17-3
+    file_5.17-3_amd64-linux-glibc_all.opk
+    file_5.17-3_amd64-linux-glibc_dev.changes
+    file_5.17-3_src_all.changes
+    libmagic-dev_5.17-3_amd64-linux-glibc_all.opk
+    libmagic-doc_5.17-3_all_all.opk
+    libmagic.1_5.17-3_amd64-linux-glibc_all.opk
+    src-file_5.17-3_src_all.opk
+
+Or from a host system on which you've been using prokit:
+
+    $ ls $root/usr/src/
+    file-doc_5.17-3_all_all.opk
+    file_5.17-3
+    file_5.17-3_amd64-linux-glibc_all.opk
+    file_5.17-3_amd64-linux-glibc_dev.changes
+    file_5.17-3_src_all.changes
+    libmagic-dev_5.17-3_amd64-linux-glibc_all.opk
+    libmagic-doc_5.17-3_all_all.opk
+    libmagic.1_5.17-3_amd64-linux-glibc_all.opk
+    src-file_5.17-3_src_all.opk