====== HyperbolaBSD Development Guidelines ======

<note warning>
This article is still in progress and is expected to be finished soon.
</note>

===== Preparations for development-environment =====

Before going forward a generic setup with a valid installation for **OpenBSD 7.0** is needed as HyperbolaBSD is also in need for testing-environment. We recommend to use an official mirror offering that version like [[https://mirrors.dotsrc.org/pub/OpenBSD/|mirrors.dotsrc.org]]. You can find the needed data and ISO-file [[https://mirrors.dotsrc.org/pub/OpenBSD/7.0/amd64/|here]].

<note warning>
As Richard Stallman said in [[https://www.gnu.org/philosophy/is-ever-good-use-nonfree-program.html#f2|the second footnote of his article "Is It Ever a Good Thing to Use a Nonfree Program?"]], **it is legitimate to recommend running some nonfree software momentarily in order to remove it**.

Therefore, **Hyperbola Project clarifies here** which is recommending the OpenBSD installation in a virtual machine in order to replace it with HyperbolaBSD. Once the official HyperbolaBSD live image be ready, this part of the documentation will be removed.
</note>

<note important>
Please note that **AMD64 (x86_64)** is mandatory needed for the moment.
</note>

You should setup your preferred way for virtualization, either with [[https://www.hyperbola.info/packages/?q=qemu|qemu]] or [[en:manual:virtual_machine_manager|qtemu]].

===== HyperbolaBSD/OpenBSD mount point suggestions =====

<note important>
Notes:
  * **BSD partitions/slices** start with **"a"** as root, **"b"** as swap and **"c"** as entire device.\\
  * **MBR** and **GUID** partition start with **"i"** as primary partition.\\
  * Unpartition storages always use** "c"**.
</note>

Mount the root **FFS2** as secondary device:

<code bash>
# mkdir hbbsd_dir/
</code>

<code bash>
# mount /dev/sd1a hbbsd_dir/
</code>

Mount a primary **EXT2** as third device:
<code bash>
# mkdir ext2_dir/
</code>

<code bash>
# mount /dev/sd2i ext2_dir/
</code>

===== Getting the source code and building the kernel (HyperBK) =====

The following requirements are needed:

  * **GCC** and **Binutils** in cross compiling \\ as **arch-machine-hyperbolabsd** triplet \\ **(example: x86_64-unknown-hyperbolabsd)**
  * **BSD make** and **Athena Jot**.

The next preparation steps are:

  * Install **GCC** and **Binutils** for HyperbolaBSD cross compilation.<code bash>
    $ TARCH=x86_64-unknown-hyperbolabsd</code><code bash>
    $ doas pacman -S $TARCH-gcc $TARCH-binutils</code>
  * Install **BSD make** and **Athena Jot**.<code bash>
    $ doas pacman -S bmake athena-jot</code>
  * Clone this repository as name **sys**:<code bash>
    $ git clone https://git.hyperbola.info:50100/hyperbolabsd/hyperbk.git</code>
  * Access the directory **hyperbk/arch/amd64/compile/GENERIC.MP**:<code bash>
    $ KARCH=amd64 KCFG=GENERIC.MP</code><code bash>
    $ cd hyperbk/arch/$KARCH/compile/$KCFG; unset KARCH KCFG</code>
  * Copy the directory **obj_gen** to **obj**:<code bash>
    $ cp -va obj_gen obj</code>
  * Access the **obj** directory:<code bash>
    $ cd obj</code>
  * Make the //HyperbolaBSD// kernel //("bmake install" to install this kernel)//:<code bash>
    $ NTHREADS=2</code><code bash>
    $ bmake -j $NTHREADS CC=$TARCH-cc LD=$TARCH-ld</code><code bash>
    $ unset CC LD NTHREADS TARCH</code>

Steps to clean source code:<code bash>
    $ KARCH=amd64 KCFG=GENERIC.MP</code><code bash>
    $ cd hyperbk/arch/$KARCH/compile/$KCFG; unset KARCH KCFG</code><code bash>
    $ bmake clean</code>

<note important>
For more information see:

  * **https://man.openbsd.org/release** \\ //(Build and install a new kernel)//
  * **https://man.openbsd.org/config** \\ //(BSD kernel configuration)//
</note>

===== Getting the source code and building the user space (alpha) =====

The following requirements are needed:

  * **GCC** and **Binutils** in cross compiling \\ as **arch-machine-hyperbolabsd** triplet \\ **(example: x86_64-unknown-hyperbolabsd)**
  * **BSD make**, **rpcsvc-proto**, **Sharutils** and **Universal Ctags**.
  * **OpenBSD lorder** (use **usr.bin/lorder/lorder.sh**), \\ due the BSD lorder from **bsdmainutils** is works different.

The next preparation steps are:

  * Install **GCC** and **Binutils** for HyperbolaBSD cross compilation.<code bash>
    $ TARCH=x86_64-unknown-hyperbolabsd</code><code bash>
    $ doas pacman -S $TARCH-gcc $TARCH-binutils</code>
  * Install **BSD make**, **rpcsvc-proto**, **Sharutils** and **Universal Ctags**.<code bash>
    $ doas pacman -S bmake rpcsvc-proto sharutils ctags</code>
  * Clone this repository:<code bash>
    $ URL=https://git.hyperbola.info:50100</code><code bash>
    $ git clone $URL/hyperbolabsd/userspace-alpha.git</code><code bash>
    $ unset URL</code>
  * Install **OpenBSD lorder**.<code bash>
    $ cd userspace-alpha</code><code bash>
    $ doas cp usr.bin/lorder/lorder.sh /usr/local/bin/lorder</code><code bash>
    $ doas chown 0:0 /usr/local/bin/lorder</code><code bash>
    $ doas chmod 0755 /usr/local/bin/lorder</code>
  * Prepare the **HyperBK™** source code:<code bash>
    $ ./sys.sh</code>
  * Generate **obj** directories:<code bash>
    $ bmake -f obj.mk</code>

  * Make the //HyperbolaBSD// kernel //("bmake install" to install this kernel)//:<code bash>
    $ NTHREADS=2</code><code bash>
    $ bmake -m $PWD/share/mk -j $NTHREADS CC=$TARCH-cc LD=$TARCH-ld</code><code bash>
    $ unset CC LD NTHREADS TARCH</code>

Steps to clean source code:<code bash>
    $ cd userspace-alpha</code><code bash>
    $ bmake -m $PWD/share/mk clean</code><code bash>
    $ bmake -f obj.mk clean</code>

<note important>
Notes:

  * Works with **AMD64 (x86_64)** only.
  * Some programs does not compile:
    * **sbin/unwind**
    * **usr.bin/make**
    * **usr.bin/nm**
    * **usr.bin/unifdef**
    * **usr.bin/vi**
    * **usr.sbin/nsd**
    * **usr.sbin/pkg_add**
    * **usr.sbin/switchd**
    * **usr.sbin/unbound**
    * **gnu**
    * **games**
</note>

===== Installing OpenBSD virtual machine =====

<note important>
https://man.openbsd.org/disklabel
</note>

<code bash>
$ qemu-img create obsd.img 2.2G</code><code bash>
$ qemu-system-x86_64 -machine q35 -cpu max -smp 2 -m 4G -device intel-hda -device hda-duplex -name OpenBSD -net nic -net user,id=port1,hostfwd=tcp::2022-:22 -s -hda install70.img -hdb obsd.img -netdev user,id=mynet0,hostfwd=tcp:127.0.0.1:7922-:22 -device virtio-net,netdev=mynet0</code>

<code bash>
(I)nstall, (U)pgrade, (A)utoinstall or (S)hell? i

Choose your keyboard layout ('?' or 'L' for list) [default]
System hostname? (short form, e.g. 'foo') openbsd

Which network interface do you wish to configure? (or 'done') [em0]
IPv4 address for em0? (or 'autoconf' or 'none') [autoconf]

IPv6 address for em0? (or 'autoconf' or 'none') [none]

Which network interface do you wish to configure? (or 'done') [done]

DNS nameservers? (IP address list or 'none') [none]

Password for root account? (will not echo) openbsd
Password for root account? (again) openbsd
Start sshd(8) by default? [yes]
Do you expect to run the X Window System? [yes]
Do you want the X Window System to be started by xenodm(1)? [no]
Change the default console to com0? [no]
Setup a user? (enter a lower-case loginname, or 'no') [no] openbsd
Full name for user openbsd? [openbsd] OpenBSD
Password for user openbsd? (will not echo) openbsd
Password for user openbsd? (again) openbsd

Allow root ssh login? (yes, no, prohibit-password) [no]

Which disk is the root disk? ('?' for details) [sd0] sd1

Use (W)hole disk MBR, whole disk (G)PT or (E)dit? [whole]

Use (A)uto layout, (E)dit auto layout, or create (C)ustom layout? [a]

Which disk do you wish to initialize? (or 'done') [done]

Location of sets? (cd0 disk http nfs or 'done') [cd0] disk
Is the disk partition already mounted? [yes] no

Which disk contains the install media? (or 'done') [sd0]

Which sd0 partition has the install sets? (or 'done') [a]
Pathname to the sets? (or 'done') [7.0/amd64]

Set name(s)? (or 'abort' or 'done') [done]
Directory does not contain SHA256.sig. Continue without verification? [no] yes

Location of sets? (cd0 disk http nfs or 'done') [done]

What timezone are you in? ('?' for list) [Canada/Montain] Etc/UTC

Exit to (S)hell, (H)alt or (R)eboot? [reboot] h</code>

===== Creating image storage with EXT2 file system =====

<code bash>
$ qemu-img create ext2.img 5G</code><code bash>
$ qemu-system-x86_64 -machine q35 -cpu max -smp 2 -m 4G -device intel-hda -device hda-duplex -name OpenBSD -net nic -net user,id=port1,hostfwd=tcp::2022-:22 -s -hda obsd.img -hdb ext2.img -netdev user,id=mynet0,hostfwd=tcp:127.0.0.1:7922-:22 -device virtio-net,netdev=mynet0</code>

<code bash>
# newfs_ext2fs -IO 1 sd1c</code><code bash>
# halt -p</code>

===== Building a modified OpenBSD bootloader to support HyperbolaBSD kernel =====

<note important>
https://man.openbsd.org/release \\
https://www.openbsd.org/anoncvs.html
</note>

<code bash>
$ qemu-system-x86_64 -machine q35 -cpu max -smp 2 -m 4G -device intel-hda -device hda-duplex -name OpenBSD -net nic -net user,id=port1,hostfwd=tcp::2022-:22 -s -hda obsd.img -hdb ext2.img -netdev user,id=mynet0,hostfwd=tcp:127.0.0.1:7922-:22 -device virtio-net,netdev=mynet0</code>

<code bash>
$ cd /usr</code><code bash>
$ cvs -qd anoncvs@anoncvs.ca.openbsd.org:/cvs checkout -rOPENBSD_7_0 -P src</code><code bash>
$ cvs -d anoncvs@anoncvs.spacehopper.org:/cvs checkout -P src</code><code bash>
Are you sure you want to continue connecting (yes/no)? yes</code>

<code bash>
nano /usr/src/sys/sys/disklabel.h:
---
-#define       DOSPTYP_OPENBSD 0xa6            /* OpenBSD partition type */
+#define       DOSPTYP_OPENBSD 0x6a            /* HyperbolaBSD partition type */
</code>

<code bash>
# cd /usr/src/sys/arch/amd64/compile/GENERIC.MP</code><code bash>
# make obj</code><code bash>
# make config</code><code bash>
# make</code><code bash>
# mount -t ext2fs /dev/sd1c /mnt</code><code bash>
# cd /usr/obj/??</code><code bash>
# cp -va biosboot boot /mnt</code><code bash>
# umount /mnt</code><code bash>
# halt -p</code>

===== Adapting a duplicated OpenBSD virtual machine =====

  * Duplicate the //OpenBSD virtual machine// image //obsd.img//:<code bash>
     $ cp obsd.img hbbsd.img</code>
  * Run virtual machine with two images **obsd.img** and **hbbsd.img**.
  * Install the modified //OpenBSD bootlader// (//boot// and //biosboot//) in **hbbsd.img**.
  * Move all //OpenBSD user space// into a **/OPENBSD/** directory in **hbbsd.img**.
  * Remove OpenBSD kernels in **hbbsd.img**.
  * Change the A6 to 6A partition type in **hbbsd.img**.

===== Extracting the OpenBSD user space =====

===== Creating the HyperbolaBSD user space package =====

Create the HyperbolaBSD userspace, with same as locations, owners, groups and permissions from OpenBSD userspace.

<code bash>
# cd hbsd_base/var/sysmerge/etc_dir/</code><code bash>
# bsdtar cvozf ../etc.tgz --options gzip:compression-level=9 *</code><code bash>
# cd ..</code><code bash>
# rm -r etc_dir</code><code bash>
# cd hbsd_base/</code><code bash>
# bsdtar cvzf ../hbbsd_base.tgz *</code>

===== Adding HyperbolaBSD packages in install70.img =====

<code bash>
$ qemu-system-x86_64 -machine q35 -cpu max -smp 2 -m 4G -device intel-hda -device hda-duplex -name OpenBSD -net nic -net user,id=port1,hostfwd=tcp::2022-:22 -s -hda obsd.img -hdb install70.img -hdc ext2.img -netdev user,id=mynet0,hostfwd=tcp:127.0.0.1:7922-:22 -device virtio-net,netdev=mynet0</code><code bash>
# mkdir ext2_dir</code><code bash>
# mount /dev/sd1a /mnt</code><code bash>
# mount -t ext2fs /dev/sd2c ext2_dir</code><code bash>
# mkdir /mnt/hbbsd</code><code bash>
# cp -va /mnt/7.0/amd64/INSTALL.amd64 /mnt/hbbsd</code><code bash>
# cd ext2_dir</code><code bash>
# cp -va bsd bsd.mp bsd.rd /mnt/hbbsd</code><code bash>
# cp -va hbbsd_base.tgz /mnt/hbbsd/base70.tgz</code><code bash>
# cd /mnt/hbbsd</code><code bash>
# sha256 * > SHA256</code><code bash>
# chmod 0644 *</code><code bash>
# chmod 0755 bsd bsd.mp</code><code bash>
# chown build:2000 *</code><code bash>
# chown 0 INSTALL.amd64 bsd.rd</code><code bash>
# chown 0:wheel SHA256</code><code bash>
# cd</code><code bash>
# umount /mnt</code><code bash>
# umount ext2_dir</code><code bash>
# rmdir ext2_dir</code><code bash>
# halt -p</code>

===== Installing HyperbolaBSD virtual machine =====

<code bash>
$ qemu-img create hbbsd_inst.img 2.2G</code><code bash>
$ qemu-system-x86_64 -machine q35 -cpu max -smp 2 -m 4G -device intel-hda -device hda-duplex -name HyperbolaBSD -net nic -net user,id=port1,hostfwd=tcp::2022-:22 -s -hda install70.img -hdb hbbsd_inst.img -netdev user,id=mynet0,hostfwd=tcp:127.0.0.1:7922-:22 -device virtio-net,netdev=mynet0</code>

<code bash>
(I)nstall, (U)pgrade, (A)utoinstall or (S)hell? i

Choose your keyboard layout ('?' or 'L' for list) [default]
System hostname? (short form, e.g. 'foo') hyperbolabsd

Which network interface do you wish to configure? (or 'done') [em0]
IPv4 address for em0? (or 'autoconf' or 'none') [autoconf]

IPv6 address for em0? (or 'autoconf' or 'none') [none]

Which network interface do you wish to configure? (or 'done') [done]

DNS nameservers? (IP address list or 'none') [none]

Password for root account? (will not echo) hyperbolabsd
Password for root account? (again) hyperbolabsd
Start sshd(8) by default? [yes]
Do you expect to run the X Window System? [yes]
Do you want the X Window System to be started by xenodm(1)? [no]
Change the default console to com0? [no]
Setup a user? (enter a lower-case loginname, or 'no') [no] hyperbolabsd
Full name for user hyperbolabsd? [hyperbolabsd] HyperbolaBSD
Password for user hyperbolabsd? (will not echo) hyperbolabsd
Password for user hyperbolabsd? (again) hyperbolabsd

Allow root ssh login? (yes, no, prohibit-password) [no]

Which disk is the root disk? ('?' for details) [sd0] sd1

Use (W)hole disk MBR, whole disk (G)PT or (E)dit? [whole]

Use (A)uto layout, (E)dit auto layout, or create (C)ustom layout? [a]

Which disk do you wish to initialize? (or 'done') [done]

Location of sets? (cd0 disk http nfs or 'done') [cd0] disk
Is the disk partition already mounted? [yes] no

Which disk contains the install media? (or 'done') [sd0]

Which sd0 partition has the install sets? (or 'done') [a]
Pathname to the sets? (or 'done') [7.0/amd64] hbbsd

Set name(s)? (or 'abort' or 'done') [done]
Directory does not contain SHA256.sig. Continue without verification? [no] yes


Location of sets? (cd0 disk http nfs or 'done') [done]

What timezone are you in? ('?' for list) [Canada/Montain] Etc/UTC
</code><code bash>
# halt -p</code>

<code bash>
$ qemu-system-x86_64 -machine q35 -cpu max -smp 2 -m 4G -device intel-hda -device hda-duplex -name HyperbolaBSD -net nic -net user,id=port1,hostfwd=tcp::2022-:22 -s -hda obsd.img -hdb hbbsd.img -hdc hbbsd_inst.img -netdev user,id=mynet0,hostfwd=tcp:127.0.0.1:7922-:22 -device virtio-net,netdev=mynet0</code><code bash>
# mkdir hbbsd_dir</code><code bash>
# mount /dev/sd1a hbbsd_dir
</code><code bash>
# mount /dev/sd2a /mnt
</code><code bash>
# cd /mnt
</code><code bash>
# cp -va altroot bin bsd bsd.mp bsd.rd dev etc home mnt root sbin tmp usr var hbbsd_dir
</code><code bash>
# umount hbbsd_dir
</code><code bash>
# umount /mnt
</code><code bash>
# rmdir hbbsd_dir
</code><code bash>
# halt -p</code>