[docs][ci-skip] document new build process

sos-os · Oct 2, 2016 · 3dad67a · 3dad67a
1 parent db031fd
commit 3dad67a
Show file tree

Hide file tree

Showing 2 changed files with 89 additions and 31 deletions.
diff --git a/BUILDING.md b/BUILDING.md
@@ -0,0 +1,84 @@
+setting up a dev environment
+============================
+
+installing Rust
+---------------
+
+In order to build SOS, you need an up-to-date version of the Rust compiler. SOS uses several gated features that can only be built on the nightly Rust release channel.
+
+The suggested way to install Rust is using [Rustup](https://www.rustup.rs), a tool for managing multiple versions of Rust. If you don't have Rustup installed, you can install it by running this command in your terminal:
+```
+$ curl https://sh.rustup.rs -sSf | sh
+```
+
+Once Rustup is installed, run
+```
+$ rustup update nightly
+```
+
+to ensure the nightly release branch is up to date.
+
+If you've set the stable or beta Rust release channels as the global default, you should run
+```
+$ rustup override nightly
+```
+in the SOS root directory, to set the nightly release channel as the default for SOS.
+
+installing dev dependencies
+---------------------------
+
+Once you have Rust installed, you will need the following additional dependencies:
++ `nasm`
++ `ld`
++ `grub-mkrescue` & `xorriso`
++ `qemu` for running the kernel under emulation
+
+Depending on your OS, you'll want to install these dependencies somewhat differently.
+
+### linux
+
+On Debian you can install them with
+
+```
+$ sudo apt-get install nasm xorriso qemu build-essential
+```
+On Arch Linux you can install them with
+```
+$ sudo pacman -S --needed binutils grub libisoburn nasm qemu
+```
+And on Fedora with
+```
+$ sudo dnf install nasm xorriso qemu
+```
+
+### macOS
+
+Installing dev dependencies on macOS is slightly trickier, as you will also need a cross-compiled version of GNU `binutils` to build SOS. Cross-compiling `binutils` will require some additional dependencies.
+
+You can install a majority of dependencies using the [Homebrew](https://github.com/Homebrew/brew) package manager. I've included a `Brewfile` for automatically installing these dependencies. To use the `Brewfile`, run the following sequence of commands:
+
+```
+$ brew update
+$ brew tap Homebrew/bundle
+$ brew bundle
+```
+
+Once you've installed the `Brewfile`, you'll need to cross-compile `binutils`. Right now, the best way to go about that is to run [this shell script](http://intermezzos.github.io/book/appendix/osx-install.html) by Steve Klabnik. I'm working on further automating the dev environment setup process on OS X, so this may get easier soon.
+
+Once the script is complete, add the following to `~/.cargo/config`:
+```yaml
+[target.x86_64-unknown-sos-gnu]
+linker = "/Users/yourusername/opt/bin/x86_64-pc-elf-gcc"
+```
+
+### windows
+Seriously?
+Windows isn't supported; I can't possibly advise it.
+
+installing `xargo`
+-----------------
+
+Once you've installed Rust and the dev dependencies, you'll need to install [`xargo`](https://github.com/japaric/xargo), a tool for cross-compiling Rust programs. You can install `xargo` quite easily by running
+```
+$ cargo install xargo
+```
diff --git a/README.md b/README.md
@@ -21,36 +21,10 @@ Design goals
 Building & Running
 ------------------
 
-This project includes Git submodules; you will want to clone it using `git clone --recursive` or run `git submodule update --init` after cloning.
+#### setting up your development environment
+In order to build SOS, you'll need to properly configure your development environment. I'm working on including a shell script to automate the setup process, but for now, you'll need to follow the instructions in BUILDING.md.
 
-#### You will need:
-
-+ Rust; I strongly recommend installing it using [rustup](https:/www./rustup.rs)
-+ `nasm`
-+ `grub-mkrescue` and possibly `xorriso` depending on whether your system considers it to be part of the `mkrescue` package (ugh)
-+ `qemu`, specifically `qemu-system-x86_64`; unless you want to try SOS on bare metal (which I cannot possibly endorse)
-
-Alternatively, if you want to use Vagrant to get a working development environment right out of the box, all you need is Vagrant installed. The Vagrantfile in this repo will take care of automatically provisioning a dev environment with everything you need to build the OS.
-
-#### Setting up
-You only need to run these steps once
-+ `$ rustup override nightly`
-+ `$ make runtime` compiles the patched `libcore`, and the Rust `libcollections`, and `liballoc` libraries (it will need to be run every time you change Rust versions)
-
-#### Running the OS
+#### building & running the OS
+  + `$ make kernel` compiles & links the kernel binary
+  + `$ make iso` makes the kernel and builds a bootable ISO image
   + `$ make run` compiles the kernel, makes the ISO, and boots QEMU from the ISO
-
-#### Using Vagrant
-
-To avoid tooling and dependency hell (especially on Macs), I'm using a Vagrant config written by @raphael-enochian based on one by @ashleygwilliams (see her repo [here](https://github.com/ashleygwilliams/x86-kernel)). Vagrant will ensure you have a dev environment with everything necessary to build SOS right out of the box.
-
-To run using vagrant (from the repo root directory):
-
- + `$ vagrant up`
- + `$ vagrant ssh -- -Y`
- + `$ cd /vagrant`
- + Follow the instructions from above
-
-#### Updating Rust Versions
-
-If you update your Rust version to a new nightly (i.e. by running `$ rustup update nightly`), you must also update the Rust library submodules. This can be done by running the command `$ git submodule foreach git pull origin`.