Skip to content

User_documentation

Jump to bottom
Zaplana Fabien edited this page Apr 21, 2021 · 9 revisions

Last update : 2020-2021

User's documentation

In this page, you will find all useful details for an user to go further in this project use. If you want to learn more or to help, we advise you to read the developers documentation afterward.

Table of content :

Pull the TuxML project

To begin, you need to pull git repositories where you want to have TuxML :
git clone https://github.com/TuxML/tuxml.git

Or if you don't want to use git, you can download the .zip and move manually TuxML where you want.

kernel_generator.py

1. Requirement

  • python3
  • docker
  • internet access (at least for the first use to get docker images and needed if you want to send results to database)

2. How to use it

$ python3 kernel_generator.py --help
usage: kernel_generator.py [-h] [--boot] [--checksize] [--dev] [--local] [--tiny] [--configs CONFIGS [CONFIGS ...]] [--seed SEED] [--linux_version LINUX_VERSION] [--compiler COMPILER] [--logs LOGS] [-s]
                           [--unit_testing] [-n NUMBER_CPU]
                           [nbcontainer] [incremental]

positional arguments:
  nbcontainer           Provide the number of container to run. Have to be over 0.
  incremental           Optional. Provide the number of additional incremental compilation. Have to be 0 or over.

optional arguments:
  -h, --help            show this help message and exit
  --boot                Optional. Try to boot the kernel after compilation if the compilation has been successful
  --checksize           Optional. Compute additional size measurements on the kernel and send the results to the 'sizes' table (can be heavy).
  --dev                 Use the image with dev tag instead of prod's one.
  --local               Don't try update the image to run, i.e. use the local version.
  --tiny                Use Linux tiny configuration. Incompatible with --configs argument.
  --configs CONFIGS [CONFIGS ...]
                        Give a path to specific configuration files. Incompatible wit --tiny argument.
  --seed SEED           Give a path to a specific seed options file. These options will be activated before the others are randomly chosen. The file will replace tuxml.config
  --linux_version LINUX_VERSION
                        Optional. Give a specific linux version to compile (can be v4 or v5). Note that its local, will take some time to download the kernel after compiling, and that the image use to compile
                        it will be deleted afterward.
  --compiler COMPILER   Optional. Give a specific compiler version.
  --logs LOGS           Optional. Save the logs to the specified path.
  -s, --silent          Prevent printing on standard output when compiling. Will still display the feature warning.
  --unit_testing        Optional. Run the unit testing of the compilation script. Prevent any compilation to happen. Will disable --tiny, --configs, --linux_version, --silent, --fetch_kernel and incremental
                        feature during runtime.
  -n NUMBER_CPU, --number_cpu NUMBER_CPU
                        Optional. Specify the number of cpu cores to use while compiling.Useful if your computer can't handle the process at full power.

Here are some examples to get you started:

  • A simple compilation: kernel_generator.py (nothing else !)
  • With unit testing : kernel_generator.py –unit-testing
  • With a custom .config file: kernel_generator.py –config <path/to/.config>
  • Running 100 compilations on 2 cpu cores: kernel_generator.py 100 -n 2 or kernel_generator.py 100 –number_cpu 2
  • Running 4 compilations on 16 cpu cores with kernel version 4.15.1: kernel_generator.py 4 -n 16 –linux4_version 15.1

3. Example of commands

  • A simple compilation: python3 kernel_generator.py
  • With unit testing: python3 kernel_generator.py --unit-testing
  • With a custom .config file: python3 kernel_generator.py --config /.config
  • With gcc version 8 : python3 kernel_generator.py --compiler gcc8
  • Running 100 compilations on 2 cpu cores: python3 kernel_generator.py 100 -n 2 or python3 kernel_generator.py 100 --number_cpu 2
  • Running 4 compilations on 16 cpu cores with kernel version 4.15.1: python3 kernel_generator.py 4 -n 16 --linux_version 4.15.1

4. Check results

  • TuxML Website: https://tuxmlweb.istic.univ-rennes1.fr
  • Local generated .json: if you use the argument --json you will find a json file locally with the result of the compilation in the root folder Json/

What's next

Consult the Developer's documentation

https://tuxmlweb.istic.univ-rennes1.fr

Clone this wiki locally