# GNU Hurd website ## Index 1. Introduction to the Hurd 2. Getting starter (for users) 3. How to contribute (for developers) 4. Documentation 1. How It works: Hurd architecture 2. Developer docs: 1. Source code: list of files and functions 2. Deep details about Hurd and Mach ### Getting started GNU/Hurd is in active development, and is not stable enough to be used in production environments. Anyway, you can test GNU/Hurd in virtual machine, and in a some old PCs. Some GNU/Linux distributions, like Debian, Arch or Guix, have variants based in Hurd. To start with Hurd, we recomments to use Debian GNU/Hurd. #### Debian GNU/Hurd ###### Prebuilt images for virtual machines To give Debian GNU/Hurd a try, it is probably easier to simply run the preinstalled image, which is provided here: $ wget http://cdimage.debian.org/cdimage/ports/10.0/hurd-i386/debian-hurd.img.tar.xz $ tar xJf debian-hurd.img.tar.xz All the debian-hurd.img* files are the same, they are just in various format, because it has been reported that some tools are not able to cope with the sparse tar format. The .tar.xz is still the preferred, as it will produce a sparse file on your disk. You can compare the resulting .img file with the MD5SUMS file It can be run directly in qemu/kvm (make sure that you can access /dev/kvm to get full KVM speed): $ kvm -m 1G -drive file=debian-hurd*.img,cache=writeback It is often convenient to connect through ssh to the box, instead of logging on the console, this can be done by forwarding the ssh port: $ kvm -net user,hostfwd=tcp:127.0.0.1:2222-:22 -net nic -drive file=debian-hurd*.img,cache=writeback -m 1G and then you can connect through ssh: ssh demo@localhost -p 2222 (don't forget to first set a password for the demo user) One can increase the size of the image with e.g.: $ qemu-img resize debian-hurd*.img +5G $ parted debian-hurd*.img (parted) resizepart 2 100% (parted) quit $ sudo losetup -o $((512*1953792)) /dev/loop0 debian-hurd*.img $ sudo resize2fs /dev/loop0 $ sudo losetup -d /dev/loop0 (1953792 is the start sector shown in fdisk -l debian-hurd*.img) It can also be run in virtualbox (though it is much less tested), by first converting to VDI format : $ VBoxManage convertfromraw debian-hurd.img debian-hurd.vdi --format vdi You can then just log in as root without a password. The qemu/kvm -curses option can be used to run it in text mode, which can help with the keyboard layout, but it's better to simply reconfigure the layout by running dpkg-reconfigure keyboard-configuration You can find more information in https://cdimage.debian.org/cdimage/ports/current-hurd-i386/README.txt #### Debian GNU/Hurd installation The preinstalled image allows to do a quick test of the system, but sometimes could be interesting doing our own installation. This section offers a how-to for Debian GNU/Hurd installation. ###### Hardware requirements + `>=` 256 MB RAM + Wired connection * NIC compatible with pcnet or Intel e1000 + Hard Disk: * SATA AHCI, SATA in IDE-compatible mode or IDE - CD/DVD drive ##### Download Debian GNU/Hurd images To install Debian GNU/Hurd, It's necessary to download the iso image. The latest image can be downloaded from [here](https://cdimage.debian.org/cdimage/ports/latest/hurd-i386/current/) #### Preparing the environment - **Real hardware** Debian GNU/Hurd can works over real hardware, although, depending of the machine, It can suffer many hardware limitation and even, sometimes, don't offers video signal. Some models which has been tested with successfull results are Thinkpad T60, R60e, X61 and T410. These models includes good compatibility with network drivers, video and mouse. For installation over real hardware, It's necessary to burn the iso image over a DVD, and boot the machine using that. Other option could be extract the harddisk, connect It as external, and execute the installer over a virtual machine, setting as destination the external harddisk. - **Virtual Machine** If you prefers to install Debian GNU/Hurd over a virtual machine, you can use VirtualBox or Qemu. For Qemu, you can get a configuration script [here](https://gist.github.com/AlmuHS/73bae6dadf19b0482a34eaab567bfdfa) For VirtualBox, you can set "Debian (32 bit)" profile, and set the network card model as "pcnet" (add some screenshots of VirtualBox configuration) #### Installation Once the installation environment is ready, you can start the installation booting from cdrom (or iso image), and selecting "Pseudographical install" into the installer. You can read a step-to-step guide to installation [here](https://gist.github.com/AlmuHS/f0c036631881756e817504d28217a910) (Explain more about installation) #### After install configurations and some tips Read https://www.debian.org/ports/hurd/hurd-install (Add some tips after installing) ### How to contribute #### Contacting with the developers To talk with the developer, there are two ways - Maillist: Hurd has many maillist to write with other users and developers. Currently, the most active is "bug-hurd". You can join to this maillist from this [link](https://lists.gnu.org/mailman/listinfo/bug-hurd) - IRC: Hurd has a IRC channel in Freenode, called #hurd For enter in It, you must to [register a nickname in freenode](https://howchoo.com/g/ndnlnzczmgz/register-nickname-freenode) Once registered, you can enter to the channel using IRC clients like Pidgin or XChat. Or, from the webbrowser, using [freenode-webchat](https://webchat.freenode.net/) #### Contributing to source code ##### Getting sources The Hurd and Mach sources are stored in Savannah (http://git.savannah.gnu.org/cgit/hurd/) You can download them using Git For Hurd sources: git://git.savannah.gnu.org/hurd/hurd.git For Mach sources git://git.savannah.gnu.org/hurd/gnumach.git ##### Writing code - **Preparing environment** Before start the work, is recommended to create a new git branch. This will makes easier the generation of the patch. - **Coding style** To write code, It's recommended to follow the same coding style guide than the rest existent files. If you're editing a existent file, you might be follow the same style than the rest of the code: check tabulations, spaces between symbols, braces, comments style, etc. If you're file is new, you can check the rest of the files of the directory. If the directory contains many different coding styles, you can use a standard style: - Mach coding style, if you're working over GNU Mach - GNU coding style if you're working over Hurd (add little documentation for each coding style) ##### Generating the patch Once finished the work, you can send the contribution sending a patch to the maillist. The patch will contains the differences between the master branch and your code (usually in other branch), in "diff" format. You can generate a patch using git, with the command: git diff master [your_branch] >> [my_mod].patch replacing [your_branch] with the name of your branch, and [my_mod] with the name of your patch_file Once generated the patch, you might add a header describing the changes done in the contribution, like a commit, with a format similar to this: Author: Samuel Thibault Date: Sun Jul 19 14:18:16 2020 +0200 device intr: Fix reference leak On RPC success we have to release the passed send rights, otherwise references accumulate and we never notice when the receiver dies. * device/ds_routines.c (ds_device_intr_ack): On success, call ipc_port_release_send on the notification receive port. - **Generating a set of patches** The previous tip can be useful when the list of changes is very short. But, when the patch includes a very big list of changes, the patch can be difficult to review. To solve this problem, It's possible to split the list of changes in different patches, one for each commit. For this, you can use `git format-patch`, with the syntax: git format-patch -N replacing `N` with the number of commits to add in the patch This command generates a set of patches, with a patch for each commit. - If the number of commits is long, it's possible to squash them using `git rebase -i` (https://www.internalpointers.com/post/squash-commits-into-one-git) - But, if the number of commits is even more long (you have "tons of commits"), you can squash them manually, following these steps: 1. Do a `git diff` between your branch and master 2. From the `git diff`, extract each couple of changes to different files 3. Return to master branch, using `git checkout` 4. Generate a new branch, derived from master 5. Apply the patches one to one 1. Apply a patch 2. Check if the changes are applied successfully. Add more changes if necessary 3. Create a new commit with the correct format (using `git commit`, instead `git commit -m`) 4. Once applied all patches and done all commits, execute `git format-patch -N` to generate the patches set ##### Sending the patch To send the patch to Hurd's developers, you must to send a email to bug-hurd maillist, attaching the set of patches to this. To advice about you're sending a patch, you can add "[PATCH]" prefix to the Subject. Example: [PATCH]: Fix error in random generator Wait until developers check your patch. It's possible to ask yours to fix some things. #### Other contributions Added to source code, you can contribute with other things: write docs, help with packaging (https://www.debian.org/ports/hurd/hurd-devel-debian)... write to bug-hurd to find more information https://www.gnu.org/software/hurd/user/tlecarrour/porting_guide_for_dummies.html