To build OSv
============

0) Install perquisite packages:

   On Fedora:
     yum install boost-static genromfs libvirt

   On Debian:
     apt-get install libboost-all-dev genromfs libvirt

1) make sure all git submodules are uptodate
   -----------------------------------------

    git submodule update --init

2) build the specially patched libunwind
   -------------------------------------

    cd external/libunwind
    autoreconf -i
    sh config.sh
    make
    cp ./src/.libs/libunwind.a ../..
    cd ../..

4) build the glibc test suite

   cd external/glibc-testsuite
   make
   cd ../..

5) build osv
   ---------

    make

To run OSv
==========

    ./scripts/run.py

External Networking
===================

To start osv with external networking:

    $ sudo ./scripts/run.py -n

Inside OSv, configure netwroking like so:

    $ ifconfig virtio-net0 192.168.122.100 netmask 255.255.255.0 up
    $ route add default gw 192.168.122.1

Test networking:

    $ test TCPExternalCommunication

Debugging
=========

To build with debugging symbols, and preemption off (to not confuse gdb),
	make -j mode=debug conf-preempt=0

To clean debugging build's results, use
	make clean mode=debug

To run the debugging build:
	./scripts/run.py -d

To connect a debugger to this run:
	$ gdb build/debug/loader.elf
	(gdb) connect
	(gdb) osv syms
	(gdb) bt

To put a breakpoint early in the osv run, a useful trick is tell the vm to
reboot after setting the breakpoint:
	(gdb) hbreak function_name
	(gdb) monitor system_reset
	(gdb) c

 Tracing
 =======
 To add a static tracepoint, use the following code:
 
   tracepoint<u64, int> trace_foo("foo", "x=%x y=%d");
   
   ...
   
   
   void foo(u64 x, int y)
   {
       trace_foo(x, y);
       ...
   }
 
 Where
 
   trace_foo: an internal identifier
   "foo": a name for the tracepoint as will be visible in the log
   <u64, int>: parameters for the tracepoint
   "x=%x y=%d": format string for the tracepoint; size modifiers unneeded
 
 To enable tracepoints at runtime, use the --trace= switch:
 
   scripts/imgedit.py setargs  build/release/loader.img --trace=sched\* testrunner.so
 
 you can use multiple --trace= switches, or a single one with commas.  Shell-style wildcards
 allow enabling multiple tracepoints (as in the example). 
 
 To trace all function entries/returns in the program, build with conf-tracing=1 (clean build
 needed), and enable "function*" tracepoints, with --trace=.
 
 To view a trace, connect with gdb, and:
 
   (gdb) osv syms
   (gdb) set pagination off
   (gdb) set logging on
   (gdb) osv trace

 gdb.txt will contain the the trace.

Leak Detection
==============

Memory allocation tracking can be enabled/disabled with the gdb commands
"osv leak on", "osv leak off", but even easier is to add the "--leak"
paramter to the loader, to have it start leak detection when entering the
payload (not during OSv boot). For example:

scripts/imgedit.py setargs build/debug/loader.img --leak java.so Try3
	# runs Java class java/Try3.class with allocation tracking

scripts/imgedit.py setargs build/debug/loader.img --leak tests/tst-leak.so
	# runs tst-leak.so test with allocation tracking.

Be sure to do this on the *debug* build, not *release* build, as our
current implementation of backtrace() relies on frame pointers, which are
omitted in our release build.

Then run (scripts/run -d), wait till it ends, and then

$ gdb build/debug/loader.elf
(gdb) connect
(gdb) osv syms
(gdb) set logging on
(gdb) set height 0
(gdb) osv leak show

Please note that "osv leak show" can take a L-O-N-G time - even a few
minutes, especially when running Java, as it allocates myriads of objects
that GDB will now have to inspect.

Running java benchmarks
=======================

After running "make", do
    scripts/imgedit.py setargs build/debug/loader.img java.so -jar bench.jar

and then run normally (./scripts/run.py).