Skip to content

Build Tutorial Notes

Jump to bottom
Jonathan Appavoo edited this page Jun 13, 2019 · 5 revisions

This tutorial will guide you through the steps of building and deploying the hello-world EbbRT application. The application exists in two parts: 1) a standard Linux application that links in the hosted (Linux-compatible) EbbRT library, and 2) a bootable native elf image that built using our toolchain and can be run within a kvm-qemu virtual machine environment.

This tutorial consists of four parts:

  1. Build the EbbRT toolchain and native EbbRT libraries.
  2. Build the hosted EbbRT library for Linux.
  3. Build the front and back-end of the hello-world application.
  4. Deploy EbbRT hello-world with docker

We primarily use make and cmake to build the EbbRT libraries and applications.

System Requirements

  • = capnproto 0.4.0

  • = cmake 2.8.12

  • = docker 1.12.0

  • = gcc 5.2.0

  • = libboost 1.54.0 (coroutine and filesystem libraries)

  • = tbb 4.2.0

  • = m4 1.4.17

  • = texinfo 5.2.0

Install all the required packages (except docker, see below) on Ubunutu 16.04 with the following command:

$ apt-get install build-essential autoconf m4 texinfo cmake libboost-coroutine-dev libboost-dev libboost-filesystem-dev libtbb-dev capnproto libcapnp-dev

Instruction for installing docker on Ubuntu 16.04 are available here: https://docs.docker.com/install/linux/docker-ce/ubuntu/

Step 0. Pull down EbbRT

$ git clone --recursive [email protected]:SESA/EbbRT.git

You should be able to do this in parallel with e.g. -j2 on git 2.8 & up.

Step 1. Build and install the EbbRT toolchain

This step will build the complete toolchain and native EbbRT library. Once build, the binaries and headers are installed to a user-defined sysroot directory.

Caution, if not run in parallel it's likely to take a very long time to build our customized GNU toolchain and all libraries dependencies. Furthermore, the build and install files will consume a few gigs of disk space. For specifics, see the build stats page on the github repo wiki.

Tip: With make command include the '-j' flag to specify a parallel build.

The default make of the toolchain will build (with optimizations) and install the toolchain within the working directory.

$ make -f $EBBRT_SRCDIR/toolchain/Makefile

You can also specify the sysroot install directory. Make sure to use a FULL path,

$ make -f $EBBRT_SRCDIR/toolchain/Makefile SYSROOT=$NATIVE_INSTALL_DIR

or enable a debug build.

$ make -f $EBBRT_SRCDIR/toolchain/Makefile DEBUG=1

Step 2. Build and install EbbRT hosted library

We build the Linux library using the CMakeLists.txt file is located in $EBBRT_SRCDIR/src. Use the CMAKE_INSTALL_PATH with cmake specify a install path.

$ cmake -DCMAKE_INSTALL_PREFIX=$HOSTED_INSTALL_DIR $EBBRT_SRCDIR/src
$ make install

Step 3. Build hello-world application

The default make command will build both the application's front-end and back-end. To do so, we need to specify the location of the install directories of the sysroot and hosted libraries.

$ cd $EBBRT_SRCDIR/apps/hello-world
$ EBBRT_SYSROOT=$NATIVE_INSTALL_PATH CMAKE_PREFIX_PATH=$HOSTED_INSTALL_PATH make

That's it. Everything is build. You can now jump to Step 4, or read on to see how to build the individual front-end and back-end binaries.

A couple gotchas:

  • Front-end hello-world assume the back-end is located at ${PWD}/bm/hello-world.elf. You can change this in the source.
  • During build you will see several of the following messages. THIS IS NORMAL
System is unknown to cmake, create:
Platform/EbbRT to use this system, please send your config file to [email protected] so it can be added to cmake

How to build hello-world.elf

$ cmake -DCMAKE_TOOLCHAIN_FILE=$EBBRT_SRCDIR/src/misc/ebbrt.cmake -DCMAKE_PREFIX_PATH=$NATIVE_INSTALL_PATH $EBBRT_SRCDIR/apps/hello-world
$ make

How to build hello-world (Linux) application

$ cmake -DCMAKE_PREFIX_PATH=$HOSTED_INSTALL_PATH
$ make

Step 4. Deploy hello-world

To deploy the hello-world back-end you must have access to kvm and the CAP_NET_ADMIN capability. This can be done quickly by adding you user to the kvm and docker groups. Don't forget you must logout + login in to enables the new environment changes.

./hello-world

Running the hello-world front-end will make the necessary calls to docker to configure and boot the EbbRT back-end. The back-end is booted within a kvm-qemu VM that runs within a container. The necessary Dockerfile will be downloaded by docker when the container is created, or you can pre-fetch it ahead of time.

$ docker pull ebbrt/kvm-qemu:latest
$ docker pull ebbrt/kvm-qemu:debug

**END OF TUTORIAL **

**END OF TUTORIAL **

**END OF TUTORIAL **

**ORIGNAL NOTES **

I will document my attempts to build and use EbbRT as of Oct 20, 2016.

Hardware : 4 core Dell Laptop -- Latitude 14 3000 Series (3450)

CPUINFO 
vendor_id	: GenuineIntel
cpu family	: 6
model		: 61
model name	: Intel(R) Core(TM) i3-5005U CPU @ 2.00GHz
stepping	: 4
microcode	: 0x1d
cpu MHz		: 800.156
cache size	: 3072 KB
fpu		: yes
fpu_exception	: yes
cpuid level	: 20
wp		: yes
flags		: fpu vme de pse tsc msr pae mce cx8 apic sep mtrr pge mca cmov pat pse36 clflush dts acpi mmx fxsr sse sse2 ss ht tm pbe syscall nx pdpe1gb rdtscp lm constant_tsc arch_perfmon pebs bts rep_good nopl xtopology nonstop_tsc aperfmperf eagerfpu pni pclmulqdq dtes64 monitor ds_cpl vmx est tm2 ssse3 sdbg fma cx16 xtpr pdcm pcid sse4_1 sse4_2 x2apic movbe popcnt tsc_deadline_timer aes xsave avx f16c rdrand lahf_lm abm 3dnowprefetch epb intel_pt tpr_shadow vnmi flexpriority ept vpid fsgsbase tsc_adjust bmi1 avx2 smep bmi2 erms invpcid rdseed adx smap xsaveopt dtherm arat pln pts
bugs

Preqs

  1. install ubuntu 16.04 then: sudo apt-get update; sudo apt-get upgrade
  2. install linux toolchain requirements for building EbbRT: sudo apt-get build-essential m4 texinfo cmake
  3. install external libraries that EbbRT uses: sudo apt-get install libboost-coroutine-dev libboost-dev libboost-filesystem-dev libtbb-dev capnproto libcapnp-dev
  4. install docker as per instructions here https://docs.docker.com/engine/installation/linux/ubuntulinux/
  5. add an ebbrtdev user: sudo adduser ebbrtdev; sudo adduser ebbrtdev sudo
  6. authorize ebbrtdev to launch docker containers: sudo groupadd docker; sudo usermod -aG docker ebbrtdev
  7. login as ebbrtdev: su - ebbrtdev
  8. Get EbbRT source: git clone --recursive https://github.com/SESA/EbbRT.git

Use EbbRT source checkout to build an install of EbbRT -- these instructions assume you put EbbRT in your home dir eg. $HOME/EbbRT. Below assumes the user is the ebbrtdev user from the above prerequisite steps.

  1. create a directory for building and install EbbRT: mkdir $HOME/ebbrt-sysroot
  2. build the EbbRT toolchain (this includes the native/baremetal EbbRT library): cd $HOME/ebbrt-sysroot; make -f ../EbbRT/toolchain/Makefile

Build and install the EbbRT hosted libraries

  1. mkdir $HOME/ebbrt-sysroot/hosted
  2. cd $HOME/EbbRT/hosted; cmake -DCMAKE_INSTALL_PREFIX=$HOME/ebbrt-sysroot/hosted
  3. cd $HOME/EbbRT/hosted; make install

Build and test the helloworld app that is distributed with the EbbRT source

  1. setup: ln -s $HOME/EbbRT/apps $HOME/ebbrt-apps
  2. build the app: cd $HOME/ebbrt-apps/helloworld; EBBRT_SYSROOT=$HOME/ebbrt-sysroot/sysroot CMAKE_PREFIX_PATH=$HOME/ebbrt-sysroot/hosted make -j 
# during build you will see several of the following messages  THIS IS NORMAL
System is unknown to cmake, create:
Platform/EbbRT to use this system, please send your config file to [email protected] so it can be added to cmake

This should compete leaving you with binaries for helloworld both frontend and backend

Running the app

$ $HOME/ebbrt-apps/helloworld/Release/helloworld

'''

ebbrtdev@dev:~$ $HOME/ebbrt-apps/helloworld/Release/helloworld exec: docker network create 1476983508 exec: docker network inspect --format='{{range .IPAM.Config}}{{.Gateway}}{{end}}' 4679217d184aa537981032f7dc20a84abb3092c7af391764df8c3dee1e491994 Network Details: | network: 4679217d184a | listening on: 172.19.0.1:40597 exec: docker run -d --expose 1234 -td -P --cap-add NET_ADMIN --device /dev/kvm:/dev/kvm --device /dev/net/tun:/dev/net/tun --device /dev/vhost-net:/dev/vhost-net --net=4679217d184aa537981032f7dc20a84abb3092c7af391764df8c3dee1e491994 -e VM_MEM=2G -e VM_CPU=2 -e VM_WAIT=true --cidfile=/tmp/5676-b48c-2a8b-2c2b ebbrt/kvm-qemu:debug --gdb tcp:0.0.0.0:1234 -kernel /root/img.elf -append "host_addr=2886926337;host_port=40597;allocid=0" exec: docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' 43a31a251a281a4f0bcbb249c0c68b0e22f3132f2d8e824345f5f08af74da25d exec: /bin/sh -c "docker port 43a31a251a281a4f0bcbb249c0c68b0e22f3132f2d8e824345f5f08af74da25d | grep 1234 | cut -d ':' -f 2" exec: ping -c 1 -w 30 172.19.0.2 exec: scp -q -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no /home/ebbrtdev/ebbrt-apps/helloworld/Release/bm/helloworld.elf32 [email protected]:/root/img.elf exec: docker exec -dt 43a31a251a281a4f0bcbb249c0c68b0e22f3132f2d8e824345f5f08af74da25d touch /tmp/signal Node Allocation Details: | gdb: 172.19.0.2:1234 | gdb(local): localhost:32770 | container: 43a31a251a28 172.19.0.253: Hello World ^CRemoving container 43a31a251a28 exec: docker stop 43a31a251a281a4f0bcbb249c0c68b0e22f3132f2d8e824345f5f08af74da25d exec: docker rm -f 43a31a251a281a4f0bcbb249c0c68b0e22f3132f2d8e824345f5f08af74da25d Removing network 4679217d184a exec: docker network rm 4679217d184aa537981032f7dc20a84abb3092c7af391764df8c3dee1e491994 '''

You might see additional stuff going on as dock downloads various default container images the first time. Eventually however you should see it launch the helloworld app. You will need to ctrl-c to end the application.

Clone this wiki locally