About This Tutorial

In this tutorial you will learn how to browse the Nanvix's source code, build it and generate a live image from it. Details about the source code itself are not covered here so, if you want to learn more about Nanvix, you can refer to the Nanvix Documentation.

The Programming Environment

Nanvix is written in C and x86 assembly, and natively supports the ELF executable file type. Therefore, in order to build Nanvix you need at least a linker, a standard C compiler and a x86 assembler, that together produce a ELF 32 binary file. However, not every tool chain with such features will correctly build Nanvix, since there are some portions of the project, like the assembly source code files, that are highly tool chain dependent. To make things easier, we strongly recommend you to use the following tools:

It is important to notice that, if you are using a 64-bit platform, you may need to setup a x86 cross-compiler. Also, we encourage you to use a GNU/Linux operating system, since all the tools listed above and many other useful development tools are available for it.

The Nanvix Source Code

At the Nanvix Source Code Repository you can download the source code of any Nanvix version that you want. Nanvix versions are quite easy to understand: the first release was Nanvix 0.01 and, at each release, the version number increases. Versions prior to Nanvix 0.05 are considered Beta Versions meaning that, among many other things, they don't follow the standard source code tree established since Nanvix 0.05 and presented hereafter.

bin/
The binary directory is the output directory where compiled binary files are placed. After building Nanvix, the kernel executable image will be located there, along with other binary files.

doc/
The documentation directory is the place where all documentation delivered with the source code is located. At least the license file is located there. If you have the source code of Nanvix without this file, please contact us providing further information about where you found this source code.

img/
In the image directory you will find a blank GRUB image and other GRUB related files. We will talk about them later when showing you how to generating a live image.

include/
The include directory is the place where all public header files are located.

lib/
The library directory is the output directory where compiled static and dynamic libraries are placed. After building Nanvix the c library will be located there, with other libraries.

src/
The source directory is the place where the source code of all Nanvix projects' branches are.

tools/
The tools directory contains the source code of tools used for generating the live image.

Building Nanvix

If you are using the suggested tool chain, building any version of Nanvix is not complicated at all: just go to the root directory of the Nanvix project and run the makefile. Any compilation error indicate that your tool chain is not properly configured. Once the building has finished, all binaries are placed on the bin directory, including the kernel image.

Generating a Live Nanvix Image

Independently which version you are using, generating a live system image is very simple:

If you are attempting to generate a live image from a Nanvix version higher than 0.04, additionally, you should build and run the install utility in order to create the initrd image. Then, you just need to place it in the root directory of the mounted live image.