Buildroot Guide

Showing results for 
Search instead for 
Did you mean: 

Buildroot Guide

Buildroot Guide



Atle had created a wonderful script to build the toolchain. Please use this instead of buildroot. Please follow Install Nios II Linux.


Stop here! The following section is for buildroot. It may be outdated.

Buildroot is a set of Makefiles and patches that help to build the cross compiler, libraries, applications, Linux kernel and root filesystem. That is, building almost everything from sources to a working Linux system.

We used buildroot to create the cross compiler and uClibc for Nios II. But we perfer uClinux-dist to create the other parts for a MMU-less Linux.

To run buildroot, you must have a Linux desktop with software development packages. Login as root or use sudo to install these packages.

On Fedora,RHEL,Centos 

sudo yum install subversion make gcc ncurses-devel bison flex gawk

On Debian/Ubuntu, sudo apt-get update sudo apt-get install subversion make gcc ncurses-dev bison flex gawk gettext

You can build in any working directory as a user account, eg. in your home dir (say /home/hippo). To grab a copy of the latest version of buildroot using anonymous svn access. (If you can't use svn, you can download a Daily Snapshotssvn co svn://

And to get the latest updates, svn update

Not recommended, but if you want to enable bzero/bcopy/index/rindex support in uClibc. Edit file, buildroot/toolchain/uClibc/uClibc-0.9.29.config , around line 83, change to, UCLIBC_SUSV3_LEGACY_MACROS=y

Then configure for Nios II. Please note, if this is your first try on buildroot, you should unselect everything in 'Toolchain' first, then only select the stuff you want. You should enable fewer options until you got first build successfully.

cd buildroot

make menuconfig


Target Architecture (nios2) ---> # select and change to nios2

Target options --->

Build options --->

Toolchain ---> # select and change as follows

Toolchain type (Buildroot toolchain) --->

--- Kernel Header Options

Kernel Headers (Linux 2.6.23.x kernel headers) --->

--- uClibc Options

uClibc C library Version (uClibc 0.9.29) --->

(toolchain/uClibc/uClibc-0.9.29.config) uClibc configuration file

[ ] Enable locale/gettext/i18n support?

Thread library implementation (linuxthreads (stable/old))

[ ] Thread library debugging # optional, if you want to debug thread

[ ] Enable 'program invocation name'

--- Binutils Options

Binutils Version

() Additional binutils options

--- GCC Options

GCC compiler Version (gcc 3.4.6) --->

[ ] Enable setjmp/longjmp exceptions?

() Additional gcc options

[ ] C++ cross-compiler support

[ ] Fortran cross-compiler support

[ ] Build/install c++ compiler and libstdc++ # optional, if you want c++

[ ] Fortran cross-compiler support

[ ] Build/install c++ compiler and libstdc++?

[ ] Build/install Objective-C compiler and runtime?

[ ] Build/install Fortran compiler and runtime?

[ ] Build/install a shared libgcc # unselect

--- Ccache Options

[ ] Enable ccache support?

--- Gdb Options

[ ] Build gdb debugger for the Target

[ ] Build gdb server for the Target

[*] Build gdb for the Host # optional

GDB debugger Version (gdb 6.6)

--- elf2flt

[*] Enable elf2flt support # select

[ ] Run mklibs on the built root filesystem

--- Common Toolchain Options

[ ] Install sstrip for the target system

[ ] Install sstrip for the host/build system

[ ] Enable multilib support # optional, if you want various processor features

[ ] Enable large file (files > 2 GB) support?

[ ] Enable IPv6 # optional

[*] Enable RPC # select

[*] Enable WCHAR support # optional

[ ] Use software floating point by default

(-Os -pipe) Target Optimizations

[ ] Include target utils in cross toolchain


Package Selection for the target ---> # unselect everything

Target filesystem options ---> # unselect everything

Kernel ---> Kernel type (none) ---> # none and unselect everything

Now build everything, it will download all the sources and compile. make

Or, for Ubuntu where bash is not the default shell, make SHELL=/bin/bash (this may take a while)

After building successfully, you need to update $PATH, remove old binary toolchain (/opt/nios2/bin) and add the new build. So that the cross compiler will be in the PATH when you login Linux. Edit file ~/.bash_profile , (or ~/.profile on Debian/Ubuntu), PATH="\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\${PATH}":$HOME/path_to/buildroot/build_nios2/staging_dir/bin

Logout and login again. You can use the tools now. Run this to verify that you have it in your command search path, nios2-linux-uclibc-gcc -v

[option, only if you use 1024Hz clock tick] Before you run make, copy the attached file uClibc-0.9.29-nios2-tck-1024.patch to buildroot/toolchain/uClibc dir. This should give correct sysconf() and clock().


Optional, update to latest kernel headers. Checkout v2.6.24-uc branch of linux-2.6.git on sopc server into your working dir, eg. in your home dir.

git clone -n git:// # this will take a long time

cd linux-2.6

git remote add sopc git://

git fetch sopc

git branch --track v2.6.24-uc sopc/v2.6.24-uc

git checkout v2.6.24-uc

git pull

git diff v2.6.24 include/asm-nios2nommu arch/nios2nommu/Makefile >~/path_to/buildroot/toolchain/kernel-headers/linux-2.6.24-nios2nommu.patch

Clean, select 2.6.24 headers and make again.

cd buildroot

rm -rf *nios2*

make menuconfig

Toolchain --->

--- Kernel Header Options

Kernel Headers (Linux 2.6.24.x kernel headers) --->


Old stuff-Don't follow me.

This is a guide to nios2 uClinux. We build a 'toolchain', compile kernel, and port applications to nios2 uClinux, on a Linux platform.

If you are new to GNU tools, you'd better use the 

BinaryToolchain. You may try buildroot after you get more understanding of the tools.

NOTE, the build script below does not handle build error and rebuild. You must edit it or remove old build. The patches should be applied only once. This page contains OUT OF DATE informations. You should use UClinuxDist instead.

Let's start it step by step

  • You should use gcc3 to build this cross-compiler. as the gcc4 has problems on binutils-2.15.
  • If you use Fedora core 5, you should select development packages during installation, and run "yum update" after installation. Note: Redhat 9 is too old, that make failed.
  • For FC5, there is a compat-gcc-32 package:

su - # your root passwd

yum install compat-gcc-32

cd /usr/bin

mv gcc gcc4

ln -s gcc32 gcc


  • For FC7, use the compat-gcc-34 package:

su - # your root passwd

rpm -i compat-gcc-34-3.4.5-7.i386.rpm

cd /usr/bin

mv gcc gcc4

ln -s gcc34 gcc


  • If you already have a working buildroot toolchain, there is no need to rebuild all each time.
  • You should edit the build script, and update only what is needed.
  • If downloading (ie. wget) fails during a build, then you can workaround by using your browser to search for and download required snapshot-files from other sites into ~/download directory.
  • Then you can edit the build script, and restart from the middle.
  • If you are starting with an old build, and wish to build afresh, then you must remove all old build directories. Uncomment line1 of the build script, which will remove all old build directories.
  • (Please NOTE, the latest buildroot/uClibc/busybox snapshot may still have problems on nios2, so we will download -20060320, the last known good shot, and save them as -snapshot instead in the build script.)
  • During the build, you can cut the command lines in this guide with your brower, and paste in the shell console or save to a script. So that you can save some typing and errors.

1. login with a user account, eg, jack. do not use root account. Your home dir will be /home/jack, or in short ~/

2. download microtronix's port of nios2 linux from the forum into the ~/download dir

3. download the,attached at the end of this post, into dir ~/download cd ~/download unzip ./build The build script will download the latest snapshot,untar, patch and make. (The configs are binutils-2.15,gcc-3.4.6,uClibc-0.9.29-pre,busybox-1.1.1-pre0 and kernel header 2.6.11.) The c++ and libstdc++ will be built, too. (but they still have problems to run) The ~/rootfs dir will be created. The kenel will use this dir and ~/download/rootfs_list file to generate initramfs image. You may edit the ~/download/rootfs_list file, to add or remove dev nodes. There is a minimal .config file. The uClinux-dist will be prepared in ~/uClinux-dist-test. The apps ported by microtronix will be in ~/apps. And the 2.6.11-uc0 kernel will be in ~/linux-2.6.x , with zImage, EPCS MTD,avalon watchdog drivers added. 4. You should include this PATH to use the cross gcc after it is built PATH=$PATH:~/buildroot/build_nios2/staging_dir/bin Or you can update the path of the cross gcc in file ~/.bash_profile PATH=$PATH:$HOME/bin:$HOME/buildroot/build_nios2/staging_dir/bin so that it will be in the PATH when you login Linux.

Run this to verify that you have it in your command search path, nios2-linux-uclibc-gcc -v

Run this to verify that you have the proper busybox in FLT format, nios2-linux-uclibc-flthdr ~/rootfs/bin/busybox it should display the FLT header like this,


Magic: bFLT

Rev: 4

Build Date: Mon Mar 27 13:55:05 2006

Entry: 0x40

Data Start: 0x632c8

Data End: 0x7bb80

BSS End: 0x96750

Stack Size: 0x3e80

Reloc Start: 0x7bb80

Reloc Count: 0x344d

Flags: 0x1 ( Load-to-Ram )

5. Setup memory and io port address map of your Nios II board with <a href="/OperatingSystems/UClinux/UClinuxDist/LinuxHwselect">LinuxHwselect.

cd ~/linux-2.6.x

# generate nios2_system.h from ptf

make ARCH=nios2nommu CROSS_COMPILE=nios2-linux-uclibc- hwselect SYSPTF=your_system.ptf

Then config (see <a href="/OperatingSystems/UClinux/UClinuxDist/LinuxConfig">LinuxConfig) and compile kernel.

# config the kernel

make ARCH=nios2nommu CROSS_COMPILE=nios2-linux-uclibc- menuconfig

# compile the kernel

make ARCH=nios2nommu CROSS_COMPILE=nios2-linux-uclibc- zImage

Whenever you update the ~/rootfs, you have to compile the kernel and update the initramfs.

CHK usr/initramfs_list

CPIO usr/initramfs_data.cpio

GZIP usr/initramfs_data.cpio.gz

AS usr/initramfs_data.o

LD usr/built-in.o

If you didn't see the "CPIO" and "GZIP" in compile message, the initramfs is not updated. You will have to remove the file usr/initramfs_list in kernel dir, and compile again to force the update of initramfs.

6. Now the compressed kernel image is ready, arch/nios2nommu/boot/zImage . you can run it on windows, First, download the sof of your hardware to your board with quartusII programmer, Then open a nios2 sdk shell,

Note the drives mapping in nios2 sdk shell, drive c: is /cygdrive/c/ if you map your linux home to h: on windows with samba server, then drive h: is /cygdrive/h/ so the image file is /cygdrive/h/linux-2.6.x/arch/nios2nommu/boot/zImage

cd /cygdrive/h/linux-2.6.x/arch/nios2nommu/boot

nios2-download -g zImage


Here is the boot message on my custom board,

Uncompressing Linux... Ok, booting the kernel.

Linux version 2.6.16 jack@localhost) (gcc version 3.4.6) #1 PREEMPT Wed Mar 22 11:48:33 CST 2006

uClinux/Nios II

Altera Nios II support © 2004 Microtronix Datacom Ltd.

Built 1 zonelists

Kernel command line:

PID hash table entries: 512 (order: 9, 8192 bytes)

Dentry cache hash table entries: 16384 (order: 4, 65536 bytes)

Inode-cache hash table entries: 8192 (order: 3, 32768 bytes)

Memory available: 63616k/65536k RAM, 0k/0k ROM (733k kernel code, 546k data)

Mount-cache hash table entries: 512

io scheduler noop registered

io scheduler deadline registered (default)

NIOS serial driver version 0.0

ttyS0 (irq = 1) is a builtin NIOS UART

Freeing unused kernel memory: 468k freed (0xc0000 - 0x134000)

init started: BusyBox v1.1.1-pre0 (2006.03.20-07:53+0000) multi-call binary

BusyBox v1.1.1-pre0 (2006.03.20-07:53+0000) Built-in shell (msh)

Enter 'help' for a list of built-in commands.


(Note, don't use jtag uart in production, it will not run without a nios2-terminal connection)

12. There are many applications built into busybox, enter 'help" to find out and read doc of busybox to learn them (eg udhcp server and client). You may config busybox, for more apps or to reduce size.

cd ~/buildroot

# remove old busybox apps and links

make -C build_nios2/busybox clean

# select busybox apps

make -C build_nios2/busybox menuconfig

# build busybox again


# rebuild rootfs

rm -rf ~/rootfs

cp -a ~/buildroot/build_nios2/root ~/rootfs

cd ~/rootfs

# remove include and lib to save space

# the dev nodes are generated via ~/download/rootfs_list

rm -rf dev usr/include usr/lib

# you may use this instead of the one from buildroot

cp ~/download/inittab etc

# check busybox header

nios2-linux-uclibc-flthdr ~/rootfs/bin/busybox

Rebuild the kernel image for initramfs.( I have removed old ~/rootfs for simplicity in the example, you may have to reinstall others, such as kernel modules, apps, configs)

If you want to add or port apps to uClinux, you should think of adding it to busybox first. Because there are no shared objs, add apps to busybox will save some memory usage.

13. To use the apps ported by Microtronix. I have patched the Makefile of inetd,ftpd and boa using ~/download/mx140apps.diff . You can look at the patches and update other apps yourself. Note you have to prepare proper config files to run these apps.

To run boa web server,

cd ~/apps/boa/src


make install

mkdir ~/rootfs/etc/config

cp ~/download/boa.conf ~/rootfs/etc/config

cp ~/download/mime.types ~/rootfs/etc

mkdir ~/rootfs/home/httpd

put your index.html and other content into ~/rootfs/home/httpd . Then rebuild zImage for initramfs, boot nios2 uclinux, and run, boa&

If you want cgi, check ~/uClinux-dist-test/user/cgi_generic , in next step.

To run inetd and ftpd,

cd ~/apps/inetd


make install

cd ~/apps/ftpd


make install

echo "ftp stream tcp nowait root /bin/ftpd" >>~/rootfs/etc/inetd.conf

to use anonymous ftp user,

add "ftp:x:14:50:FTP User:/home/ftp:" to etc/passwd

add "ftp:x:50:" to etc/group

make dir home/ftp

add ftp contents to home/ftp

rebuild zImage for initramfs, boot nios uclinux, and run,


netstat -a

inetd will invoke ftpd.

14. To use user apps ported to uClinux from uClinux-dist.

cd ~/uClinux-dist-test

make menuconfig

In menuconfig, select Kernel/Library/Defaults Selection ---> [*] Customize Vendor/User Settings (NEW) Then <exit>,<exit>,<yes>. It will enter user apps select, make your selection. It has pre-selected dhcpd and net-snmp for testing.

To compile make subdirs copy apps to ~/rootfs

make romfs

cd romfs

cp -a bin usr var ~/rootfs

Note, you have to setup config files to ~/rootfs/etc for apps (eg dhcpd.conf), check doc for each of them. You should also check ~/uClinux-dist-test/romfs/etc for other config files. ~/uClinux-dist-test/user/dhcpd/samples/dhcpd.conf

Then rebuild zImage for initramfs. (note, the boa port in uClinux-dist has problems on nios2)

To use telnetd, you have to enable pty in kernel config, [code]Device Drivers --> Character devices --> [*] Legacy (BSD) PTY support (10) Maximum number of legacy PTY in use[/code] Select telnetd in uClinux-dist-test menuconfig,

[*] telnetd

[*] telnetd does not use openpty() (NEW)

add "telnet stream tcp nowait root /bin/telnetd" to ~/rootfs/etc/inetd.conf . The password files are etc/passwd,etc/group,etc/shadow .

15. If you want to port apps, look in ~/buildroot/build_nios2/busybox, ~/apps, and ~/uClinux-dist-test/user first. There may be ported apps already. Read the file INSTALL of it. If it need "./configure", you should check it with "./configure -help" and add options. You may have to update the file config.sub, check ~/download/uClinux-dist.diff on how to add $basic_machine, eg wget

Index: user/wget/config.sub


--- user/wget/config.sub (revision 1)

+++ user/wget/config.sub (revision 3)

@@ -274,6 +274,11 @@

m88110 | m680[12346]0 | m683?2 | m68360 | m5200 | v70 | w65 | z8k)



+ nios2 | nios2-* | nios2 | nios2-*)

+ basic_machine=nios2-altera

+ os=-linux



# We use `pc' rather than `unknown'

# because (1) that's what they normally are, and

# (2) the word "unknown" tends to confuse beginning users.

Then run "./configure --host=nios2-linux-uclibc --disable-shared ...." ,a Makefile will be generated. You may have to modify the Makefile or Rules.mak. The stdinc dir and stdlib dir are default to uClibc. So you don't need the "-nostdinc" and "-nostdlib" stuf. You should add something like this to link flags to generate FLT obj, [code]LDFLAGS += -Wl,-elf2flt="-s 16000" -Wl,-v -Wl,-d[/code] Remove unused items, or that is for PC host. You can setup the install path to your rootfs. Then,"make","make install". Remeber to update the kernel image for initramfs. A sample patch, mtools-Makefile.diff, to mtools-3.9.10 Makefile is included in the attached

(PS..) Marc sent the nios2 port of buildroot to, and I did some patches, too. Vapier, one of the developers of busybox/uClibc/buildroot, helps to clean up the codes and incoporate into the "trunk". And he forwarded the elf2flt patches to uClinux dev team, too. All these works bring this project, simple and easy to use tools to build uClinux for the Nios2. Best thanks to marc, jdhar, and vapier.



Version history
Last update:
‎12-19-2022 11:12 AM
Updated by: