README.md 9.2 KB
Newer Older
1
<p align="center">
Caleb Boylan's avatar
Caleb Boylan committed
2
<img alt="Redox" width="346" src="https://gitlab.redox-os.org/redox-os/assets/raw/master/logos/redox/logo.png">
3
</p>
ticki's avatar
ticki committed
4

Jonathan's avatar
Jonathan committed
5
**Redox** is an operating system written in Rust, a language with focus on safety and high performance. Redox, following the microkernel design, aims to be secure, usable, and free. Redox is inspired by previous kernels and operating systems, such as SeL4, MINIX, Plan 9, and BSD.
ticki's avatar
ticki committed
6

7
Redox _is not_ just a kernel, it's a **full-featured Operating System**, providing packages (memory allocator, file system, display manager, core utilities, etc.) that together make up a functional and convenient operating system. You can loosely think of it as the GNU or BSD ecosystem, but in a memory safe language and with modern technology. See [this list](#ecosystem) for overview of the ecosystem.
8 9

The website can be found at https://www.redox-os.org.
ticki's avatar
ticki committed
10

Jeremy Soller's avatar
Jeremy Soller committed
11
Please make sure you use the **latest nightly** of `rustc` before building (for more troubleshooting, see ["Help! Redox won't compile!"](#compile-help)).
ticki's avatar
ticki committed
12

Jeremy Soller's avatar
Jeremy Soller committed
13
[![Travis Build Status](https://travis-ci.org/redox-os/redox.svg?branch=master)](https://travis-ci.org/redox-os/redox)
Caleb Boylan's avatar
Caleb Boylan committed
14
[![Downloads](https://img.shields.io/github/downloads/redox-os/redox/total.svg)](https://gitlab.redox-os.org/redox-os/redox/tags)
Jeremy Soller's avatar
Jeremy Soller committed
15
[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
Jeremy Soller's avatar
Jeremy Soller committed
16
![Rust Version](https://img.shields.io/badge/rust-nightly%202017--10--03-lightgrey.svg)
ticki's avatar
ticki committed
17

Jeremy Soller's avatar
Jeremy Soller committed
18
## Contents
ticki's avatar
ticki committed
19

20
* [What it looks like](#screenshots)
21
* [Ecosystem](#ecosystem)
Jeremy Soller's avatar
Jeremy Soller committed
22 23 24 25 26
* [Help! Redox won't compile](#compile-help)
* [Contributing to Redox](#contributing)
* [Cloning, Building and running](#cloning-building-running)
 * [Quick Setup](#quick-setup)
 * [Manual Setup](#manual-setup)
27
 * [Setup Using Docker](#setup-using-docker)
ticki's avatar
ticki committed
28

29
## <a name="screenshots"> What it looks like </a>
ticki's avatar
ticki committed
30

Caleb Boylan's avatar
Caleb Boylan committed
31 32 33
<img alt="Redox" height="150" src="https://gitlab.redox-os.org/redox-os/assets/raw/master/screenshots/Senza%20titolo.jpeg">
<img alt="Redox" height="150" src="https://gitlab.redox-os.org/redox-os/assets/raw/master/screenshots/redox running.jpeg">
<img alt="Redox" height="150" src="https://gitlab.redox-os.org/redox-os/assets/raw/master/screenshots/IMG_1460.PNG">
ticki's avatar
ticki committed
34

Caleb Boylan's avatar
Caleb Boylan committed
35 36 37
<img alt="Redox" height="150" src="https://gitlab.redox-os.org/redox-os/assets/raw/master/screenshots/Sodium_v2.PNG">
<img alt="Redox" height="150" src="https://gitlab.redox-os.org/redox-os/assets/raw/master/screenshots/Boot.png">
<img alt="Redox" height="150" src="https://gitlab.redox-os.org/redox-os/assets/raw/master/screenshots/IMG_1459.PNG">
ticki's avatar
ticki committed
38

39 40 41 42
## <a name="ecosystem"> Ecosystem </a>

The ecosystem and software Redox OS provides is listed below.

43 44
| Name (lexicographic order)                                                           | Maintainer
|--------------------------------------------------------------------------------------|---------------------------
45
| [acid (kernel integration tests)](https://gitlab.redox-os.org/redox-os/acid)         | **@jackpot51** **@NilSet**
46
| [binutils](https://gitlab.redox-os.org/redox-os/binutils)                            | **vacant**
47
| [cookbook](https://gitlab.redox-os.org/redox-os/cookbook)                            | **@jackpot51** **@ids1024** **@sajattack**
48 49
| [coreutils](https://gitlab.redox-os.org/redox-os/coreutils)                          | **vacant**
| [extrautils](https://gitlab.redox-os.org/redox-os/extrautils)                        | **vacant**
50 51
| [games](https://gitlab.redox-os.org/redox-os/games)                                  | **@enrico** (AKA **@HenryTheCat**) **@fabiao**
| [Ion (shell)](https://gitlab.redox-os.org/redox-os/ion)                              | **@mmstick** **@stratact**
52
| [ipcd](https://gitlab.redox-os.org/redox-os/ipcd)                                    | **@jD91mZM2**
53
| [kernel](https://gitlab.redox-os.org/redox-os/kernel)                                | **@jackpot51**
54 55
| [libextra](https://gitlab.redox-os.org/redox-os/libextra)                            | **vacant**
| [libpager](https://gitlab.redox-os.org/redox-os/libpager)                            | **vacant**
56 57 58 59
| [netstack](https://gitlab.redox-os.org/redox-os/netstack)                            | **@batonius** **@dlrobertson**
| [netutils](https://gitlab.redox-os.org/redox-os/netutils)                            | **@jackpot51**
| [orbclient (Orbital client)](https://gitlab.redox-os.org/redox-os/orbclient)         | **@jackpot51** **@FloVanGH**
| [orbdata](https://gitlab.redox-os.org/redox-os/orbdata)                              | **@jackpot51**
60
| [orbgame (Orbital 2D game engine)](https://gitlab.redox-os.org/redox-os/orbgame)     | **@FloVanGH**
61
| [Orbital (windowing and compositing system)](https://gitlab.redox-os.org/redox-os/orbital) | **@jackpot51**
62
| [orbtk (Orbital toolkit)](https://gitlab.redox-os.org/redox-os/orbtk)                | **@FloVanGH**
63 64 65 66 67 68
| [orbutils (Orbital utilities)](https://gitlab.redox-os.org/redox-os/orbutils)        | **@jackpot51**
| [pkgutils (current package manager)](https://gitlab.redox-os.org/redox-os/pkgutils)  | **@jackpot51**
| [ralloc](https://gitlab.redox-os.org/redox-os/ralloc)                                | **@Tommoa** **@NilSet**
| [RANSID (Rust ANSI driver)](https://gitlab.redox-os.org/redox-os/ransid)             | **@jackpot51**
| [redoxfs (old filesystem)](https://gitlab.redox-os.org/redox-os/redoxfs)             | **@jackpot51**
| [relibc (C Library in Rust)](https://gitlab.redox-os.org/redox-os/relibc)            | **@jD91mZM2** **@sajattack** **@Tommoa** **@stratact**
stratact's avatar
stratact committed
69
| [small (stack String and other collections)](https://gitlab.redox-os.org/redox-os/small) | **@Tommoa**
70
| [syscall](https://gitlab.redox-os.org/redox-os/syscall)                              | **@jackpot51**
71
| [Sodium (Vim-inspired text editor)](https://gitlab.redox-os.org/redox-os/sodium)     | **vacant**
72
| [TFS ((ticki) **T**he **F**ile **S**ystem)](https://gitlab.redox-os.org/redox-os/tfs) | **@Tommoa**
73
| [The Redox book](https://gitlab.redox-os.org/redox-os/book)                          | **vacant**
74
| [userutils](https://gitlab.redox-os.org/redox-os/userutils)                          | **@jackpot51**
75

Jeremy Soller's avatar
Jeremy Soller committed
76
## <a name="compile-help"> Help! Redox won't compile! </a>
ticki's avatar
ticki committed
77

Jeremy Soller's avatar
Jeremy Soller committed
78
Sometimes things go wrong when compiling. Try the following before opening an issue:
ticki's avatar
ticki committed
79

Aurélien DESBRIÈRES's avatar
Aurélien DESBRIÈRES committed
80
1. Run `rustup update`
garasubo's avatar
garasubo committed
81 82 83
1. Run `make clean pull`.
1. Make sure you have **the latest version of Rust nightly!** ([rustup.rs](https://www.rustup.rs) is recommended for managing Rust versions. If you already have it, run `rustup`).
1. Update **GNU Make**, **NASM** and **QEMU/VirtualBox**.
Caleb Boylan's avatar
Caleb Boylan committed
84
1. Pull the upstream master branch (`git remote add upstream git@gitlab.redox-os.org:redox-os/redox.git; git pull upstream master`).
garasubo's avatar
garasubo committed
85
1. Update submodules (`git submodule update --recursive --init`).
ticki's avatar
ticki committed
86

Jeremy Soller's avatar
Jeremy Soller committed
87
and then rebuild!
ticki's avatar
ticki committed
88

Jeremy Soller's avatar
Jeremy Soller committed
89
## <a name="contributing"> Contributing to Redox </a>
ticki's avatar
ticki committed
90

Jeremy Soller's avatar
Jeremy Soller committed
91
If you're interested in this project, and you'd like to help us out, [here](CONTRIBUTING.md) is a list of ways you can do just that.
ticki's avatar
ticki committed
92

Emanuele Antonio Faraone's avatar
Emanuele Antonio Faraone committed
93
## <a name="cloning-building-running"> Cloning, Building and Running </a>
ticki's avatar
ticki committed
94

95
Redox is big, even compressed. Downloading the full history may take a lot of bandwidth, and can even be costly on some data plans. Clone at your own risk!
ticki's avatar
ticki committed
96

Jeremy Soller's avatar
Jeremy Soller committed
97
### <a name="quick-setup" /> Quick Setup </a>
ticki's avatar
ticki committed
98

Jeremy Soller's avatar
Jeremy Soller committed
99 100
```bash
$ cd path/to/your/projects/folder/
ticki's avatar
ticki committed
101

Jeremy Soller's avatar
Jeremy Soller committed
102
# Run bootstrap setup
Caleb Boylan's avatar
Caleb Boylan committed
103
$ curl -sf https://gitlab.redox-os.org/redox-os/redox/raw/master/bootstrap.sh -o bootstrap.sh && bash -e bootstrap.sh
ticki's avatar
ticki committed
104

Nagy Tibor's avatar
Nagy Tibor committed
105
# Change to project directory
106 107
$ cd redox

Jeremy Soller's avatar
Jeremy Soller committed
108 109
# Build Redox
$ make all
ticki's avatar
ticki committed
110

Jeremy Soller's avatar
Jeremy Soller committed
111 112
# Launch using QEMU
$ make qemu
Nagy Tibor's avatar
Nagy Tibor committed
113
# Launch using QEMU without using KVM (Kernel-based Virtual Machine). Try if QEMU gives an error.
Jeremy Soller's avatar
Jeremy Soller committed
114 115
$ make qemu kvm=no
```
ticki's avatar
ticki committed
116

Jeremy Soller's avatar
Jeremy Soller committed
117
#### QEMU with KVM
ticki's avatar
ticki committed
118

Nagy Tibor's avatar
Nagy Tibor committed
119
To use QEMU with KVM (Kernel-based Virtual Machine), which is faster than without KVM, you need a CPU with Intel® Virtualization Technology (Intel® VT) or AMD Virtualization™ (AMD-V™) support. Most systems have this disabled by default, so you may need to reboot, go into the BIOS, and enable it.
Jeremy Soller's avatar
Jeremy Soller committed
120 121 122

### <a name="manual-setup"> Manual Setup </a>

123
To manually clone, build and run Redox using a Unix-based host, run the following commands (with exceptions, be sure to read the comments):
Jeremy Soller's avatar
Jeremy Soller committed
124 125 126 127
```bash
$ cd path/to/your/projects/folder/

# HTTPS
Caleb Boylan's avatar
Caleb Boylan committed
128
$ git clone https://gitlab.redox-os.org/redox-os/redox.git --origin upstream --recursive
Jeremy Soller's avatar
Jeremy Soller committed
129
# SSH
Caleb Boylan's avatar
Caleb Boylan committed
130
$ git clone git@gitlab.redox-os.org:redox-os/redox.git --origin upstream --recursive
Jeremy Soller's avatar
Jeremy Soller committed
131 132 133 134

$ cd redox/

# Install/update dependencies
135
$ ./bootstrap.sh -d
Jeremy Soller's avatar
Jeremy Soller committed
136 137 138

# Install rustup.rs
$ curl https://sh.rustup.rs -sSf | sh
Nagy Tibor's avatar
Nagy Tibor committed
139
$ source $HOME/.cargo/env
Jeremy Soller's avatar
Jeremy Soller committed
140

141 142 143
# Install the sysroot manager Xargo
$ cargo install xargo

Jeremy Soller's avatar
Jeremy Soller committed
144 145 146 147 148 149 150 151 152 153
# For successive builds start here. If this is your first build, just continue

# Update git submodules
$ git submodule update --recursive --init

# Build Redox
$ make all

# Launch using QEMU
$ make qemu
154

Nagy Tibor's avatar
Nagy Tibor committed
155
# Launch using QEMU without using KVM (Kernel-based Virtual Machine). Try if QEMU gives an error.
Jeremy Soller's avatar
Jeremy Soller committed
156
$ make qemu kvm=no
157

Nagy Tibor's avatar
Nagy Tibor committed
158
# Launch using QEMU without using KVM (Kernel-based Virtual Machine) nor Graphics
159
make qemu kvm=no vga=no
Jeremy Soller's avatar
Jeremy Soller committed
160
```
161 162 163

### <a name="setup-using-docker"> Setup using Docker </a>
We also provide docker image. After cloning this repository, please follow README under the `docker` directory.
164 165 166 167 168 169 170 171 172

### Updating the codebase using the Makefile
To update the codebase run:

```
make pull; make fetch
```

`make pull` pulls and updates the submodules, and `make fetch` updates the sources for cookbook recipes.