From 3dad67ae9c0dcf77a2ce7a465e4d76babb38611d Mon Sep 17 00:00:00 2001 From: Hawk Weisman Date: Sun, 2 Oct 2016 16:03:58 -0400 Subject: [PATCH] [docs][ci-skip] document new build process --- BUILDING.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 36 ++++------------------- 2 files changed, 89 insertions(+), 31 deletions(-) create mode 100644 BUILDING.md diff --git a/BUILDING.md b/BUILDING.md new file mode 100644 index 00000000..9fa00260 --- /dev/null +++ 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 index 01c185b5..d835fc4a 100644 --- 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`.