README.in

README for rt-app @VERSION@

==============
 INTRODUCTION
==============

rt-app is a test application that starts multiple periodic threads in order to
simulate a real-time periodic load.

Code is currently maintained on GitHub:

	http://github.com/scheduler-tools/rt-app


==============
 REQUIREMENTS
==============

rt-app runs on GNU/Linux. It needs bash, autoconf, automake, libtool,
libjson-c, GNU make and a recent compiler (tested on: gcc) for basic features.
If your system has numactl (libnuma-dev) installed, numa features will be supported.  


=================
 BUILDING json-c
=================

If you are not happy using the version installed by your packaging system,
if it does not provide static libraries and you need them, need to
cross-compile, build it from source like this:

retrieve source code available here:

    https://github.com/json-c/json-c

cross-compile json-c and build both static and shared libraries for aarch64:

    export ac_cv_func_malloc_0_nonnull=yes
    export ac_cv_func_realloc_0_nonnull=yes
    ./autogen.sh
    ./configure --host=aarch64-linux-gnu --enable-shared --enable-static
    make


=================
 BUILDING numactl
=================

If you are not happy using the version installed by your packaging system,
if it does not provide static libraries and you need them, need to
cross-compile, build it from source like this:

retrieve source code available here:

    git clone https://github.com/numactl/numactl.git

cross-compile numactl and build static libraries for aarch64:

    ./autogen.sh
    ./configure --host=aarch64-linux-gnu --disable-shared --enable-static
    make


================================
 BUILDING AND INSTALLING rt-app
================================

VARIANT A)
cross-compile a static rt-app for aarch64, using your own json-c and/or numactl build
----------------------------------------------------------------------
(...that wasn't installed (or not into the standard locations))

    export ac_cv_lib_json_c_json_object_from_file=yes
    export ac_cv_lib_numa_numa_available=yes
    
    ./autogen.sh
    ./configure --host=aarch64-linux-gnu LDFLAGS="-L<absolute path to json repo> -L<absolute path to numactl repo>" CFLAGS="-I<path to parent of json-c repo> -I<path to parent of numactl repo>"
    AM_LDFLAGS="-all-static" make

configure supports the usual flags, like `--help` and `--prefix`, there is an
install target in the Makefile as well.


EXAMPLE: with a directory structure like the following:

    $ tree -d -L 2
    .
    ├── json-c
    │   ├── autoconf-archive
    │   ├── cmake
    │   ├── fuzz
    │       └── tests
    ├── numactl
    │   ├── m4
    │   └── test
    └── rt-app
        ├── doc
        ├── libdl
        └── src


you would run:

    cd rt-app
    export ac_cv_lib_json_c_json_object_from_file=yes
    export ac_cv_lib_numa_numa_available=yes
    ./autogen.sh
    ./configure --host=aarch64-linux-gnu LDFLAGS="-L$PWD/../json-c -L$PWD/../numactl" CFLAGS="-I$PWD/../"
    AM_LDFLAGS="-all-static" make

and you should get a static rt-app executable in the src directory.


VARIANT B)
regular build of rt-app for your host against json-c in canonical locations
---------------------------------------------------------------------------
(and installation with PREFIX=/usr/local)

    ./autogen.sh
    ./configure
    make
    make install


=======
 USAGE
=======

    $ rt-app [-l <log level>] <config_file>

where config file is a full/relative path to a json file (look under
doc/examples for examples) or "-" (without quotes) to read JSON data from
stdin.

Refer to file doc/tutorial.txt for information about how to write the json
file.