Update the README.md file to work better with github.

11 years ago · acc07d281b
parent 6b0117e623
commit acc07d281b
1 changed files with 38 additions and 28 deletions
--- a/README.md
+++ b/README.md
@ -1,6 +1,6 @@
 # Gitian

-Read about the project goals at the "project home page":https://gitian.org/ .
+Read about the project goals at the [project home page](https://gitian.org/).

 This package can do a deterministic build of a package inside a VM.

@ -10,29 +10,30 @@ This performs a build inside a VM, with deterministic inputs and outputs.  If th

 ## Prerequisites:

-Gentoo:
+### Gentoo:

    layman -a luke-jr  # needed for vmbuilder
    sudo emerge dev-vcs/git net-misc/apt-cacher-ng app-emulation/vmbuilder dev-lang/ruby
    sudo emerge app-emulation/qemu
    export KVM=qemu-system-x86_64

-Ubuntu:
+### Ubuntu:

    sudo apt-get install git apache2 apt-cacher-ng python-vm-builder ruby
    sudo apt-get install qemu-kvm         # for KVM mode
    sudo apt-get install debootstrap lxc  # for LXC mode

-OSX with MacPorts:
+### OSX with MacPorts:

    sudo port install ruby coreutils
    export PATH=$PATH:/opt/local/libexec/gnubin  # Needed for sha256sum

-### VirtualBox
+#### VirtualBox:

-Install virtualbox from virtualbox.org, and make sure VBoxManage is in your $PATH.
+Install virtualbox from http://www.virtualbox.org, and make sure `VBoxManage` is in your `$PATH`.

-## Create the base VM for use in further builds (requires sudo, please review the script):
+## Create the base VM for use in further builds
+**NOTE:** requires `sudo`, please review the script

 ### KVM

@ -44,48 +45,57 @@ Install virtualbox from virtualbox.org, and make sure VBoxManage is in your $PAT
    bin/make-base-vm --lxc
    bin/make-base-vm --lxc --arch i386

-Set the USE_LXC environment variable to use LXC instead of KVM:
+Set the `USE_LXC` environment variable to use `LXC` instead of `KVM`:
+
    export USE_LXC=1

 ### VirtualBox

-Command-line VBoxManage must be in your PATH
+Command-line `VBoxManage` must be in your `$PATH`.
+
+#### Setup:

-Setup:
+`make-base-vm` cannot yet make VirtualBox virtual machines ( _patches welcome_, it should be possible to use `VBoxManage`, boot-from-network Linux images and PXE booting to do it). So you must either get or manually create VirtualBox machines that:

-make-base-vm cannot yet make VirtualBox virtual machines (patches welcome-- it should be possible to use VBoxManage, boot-from-network Linux images and PXE booting to do it). So you must either get or manually create VirtualBox machines that:
+1. Are named `Gitian-<suite>-<arch>` -- e.g. Gitian-lucid-i386 for a 32-bit, Ubuntu 10 machine.
+2. Have a booted-up snapshot named `Gitian-Clean` .  The build script resets the VM to that snapshot to get reproducible builds.
+3. Has the VM's NAT networking setup to forward port `localhost:2223` on the host machine to port `22` of the VM; e.g.:

-1. Are named "Gitian-<suite>-<arch>" -- e.g. Gitian-lucid-i386 for a 32-bit, Ubuntu 10 machine.
-2. Have a booted-up snapshot named "Gitian-Clean" .  The build script resets the VM to that snapshot to get reproducible builds.
-3. Has the VM's NAT networking setup to forward port localhost:2223 on the host machine to port 22 of the VM; e.g.:
+```
    VBoxManage modifyvm Gitian-lucid-i386 --natpf1 "guestssh,tcp,,2223,,22"
+```

-The final setup needed is to create an ssh key that will be used to login to the virtual machine:
+The final setup needed is to create an `ssh` key that will be used to login to the virtual machine:

    ssh-keygen -t dsa -f var/id_dsa -N ""
    ssh -p 2223 ubuntu@localhost 'mkdir -p .ssh && chmod 700 .ssh && cat >> .ssh/authorized_keys' < var/id_dsa.pub
+
+Then log into the vm and copy the `ssh` keys to root's `authorized_keys` file.
+
    ssh -p 2223 ubuntu@localhost
-    On VM: sudo bash
-    On VM: mkdir -p .ssh && chmod 700 .ssh && cat ~ubuntu/.ssh/authorized_keys >> .ssh/authorized_keys
+    # Now in the vm
+    sudo bash
+    mkdir -p .ssh && chmod 700 .ssh && cat ~ubuntu/.ssh/authorized_keys >> .ssh/authorized_keys
+
+Set the `USE_VBOX` environment variable to use `VBOX` instead of `KVM`:

-Set the USE_VBOX environment variable to use LXC instead of KVM:
    export USE_VBOX=1

 ## Sanity-testing

 If you have everything set-up properly, you should be able to:

-PATH=$PATH:$(pwd)/libexec
-make-clean-vm --suite lucid --arch i386
-start-target 32 lucid-i386
-on-target ls -la
-stop-target
+    PATH=$PATH:$(pwd)/libexec
+    make-clean-vm --suite lucid --arch i386
+    start-target 32 lucid-i386
+    on-target ls -la
+    stop-target

 ## Building

 Copy any additional build inputs into a directory named _inputs_.

-Then execute the build using a YAML description file (can be run as non-root):
+Then execute the build using a `YAML` description file (can be run as non-root):

    export USE_LXC=1 # LXC only
    bin/gbuild <package>.yml
@ -94,13 +104,13 @@ or if you need to specify a commit for one of the git remotes:

    bin/gbuild --commit <dir>=<hash> <package>.yml

-The resulting report will appear in result/\<package\>-res.yml
+The resulting report will appear in `result/<package>-res.yml`

 To sign the result, perform:

    bin/gsign --signer <signer> --release <release-name> <package>.yml

-Where <signer> is your signing PGP key ID and <release-name> is the name for the current release.  This will put the result and signature in the sigs/<package>/<release-name>.  The sigs/<package> directory can be managed through git to coordinate multiple signers.
+Where `<signer>` is your signing PGP key ID and `<release-name>` is the name for the current release.  This will put the result and signature in the `sigs/<package>/<release-name>`.  The `sigs/<package>` directory can be managed through git to coordinate multiple signers.

 After you've merged everybody's signatures, verify them:

@ -114,7 +124,7 @@ After you've merged everybody's signatures, verify them:
 * To start the target VM run `start-target 32 lucid-i386` or `start-target 64 lucid-amd64`
 * To ssh into the target run `on-target` or `on-target -u root`
 * On the target, the _build_ directory contains the code as it is compiled and _install_ contains intermediate libraries
-* By convention, the script in \<package\>.yml starts with any environment setup you would need to manually compile things on the target
+* By convention, the script in `<package>.yml` starts with any environment setup you would need to manually compile things on the target

 TODO:
 - disable sudo in target, just in case of a hypervisor exploit
@ -130,7 +140,7 @@ Recent distributions allow lxc-start to be run by non-priviledged users, so you

 If you have a runaway `lxc-start` command, just use `kill -9` on it.

-The machine configuration requires access to br0 and assumes that the host address is 10.0.2.2:
+The machine configuration requires access to br0 and assumes that the host address is `10.0.2.2`:

    sudo brctl addbr br0
    sudo ifconfig br0 10.0.2.2/24 up