Dev_documentation

_{Last update : 2020-2021 (may 2021)}

Developper'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 :

• How to (re)generate TuxML images
• How to delete old images of TuxML ?
• How to mount your code without generate images when debugging ?
• How works the API ?
• How to modify Dockerfiles ?
• What is the mains sections of code ?
• How to debug inside a running TuxML container ?
• Others

How to (re)generate TuxML images

When you modify the source of TuxML you will need to regenerate de docker images of TuxML for use it.
This need is specific for every changement of source code in the folder ./compilation.

Before use it, you should delete the old images of TuxML, it's detailed here "How to delete old images of TuxML ?"

You should execute the script docker_image_tuxml.py with python3 who is inside the folder ./docker_management :

cd docker_management/ ;
python3 docker_image_tuxml.py -f ;
cd ../ ;

For help the developpers a bash script is available : ./scripts_bash/generate_images.sh

For finish, it's interesting to know that there are a way who permit to don't always need to regenerate images when you are in a developpment session and if you need to try and debug your code before you want to generate the images.

You wan use the specific options --mount_host_dev like :
python3 kernel_generator.py --local --dev 1 --tiny --mount_host_dev

This option is more detailed here "How to mount your code without generate images when debugging ?".

How to delete old images of TuxML ?

When you want to regenerate the images of TuxML after developppement, you need to remove old images before.

Be careful if you use docker for others projects than TuxML, these commands will stop and delete all running container; but don't worry it will delete only docker images of TuxML :

docker stop $(docker ps -a -q); 
docker rm -f $(docker ps -a -q); 
docker rmi $(docker images | grep 'tuxml/')
docker image prune -f

How to mount your code without generate images when debugging ?

If you are in developpment and if you need to try your code or debbuging you can use the specific options --mount_host_dev :
python3 kernel_generator.py --local --dev 1 --tiny --mount_host_dev

This option will mount your modified code inside the docker container of TuxML.

Be carefull this modification will be only in local, and temporary, if you need to permit other users to use your modifications youw will need to regenerate the images of TuxML and upload them to the repositories.

How works the API ?

For send the compilation data generated, the python script of TuxML send all the informations to the TuxML API who is in charge to contact safely the database.

The API of TuxML is developped by an other part of the TuxML team and is host in a specific server.
The sources are on an other git. (more info in the specific documentation of TuxML Web)

If you are a developper of TuxML, you need to know 2 main thing :

• the API manager is ./compilation/apiManager.py, usefull if you need to modify the connection to the API
• the content send to the API is in the format "json" and is created in ./compilation/main.py

How to modify Dockerfiles ?

Sometimes you will need to add some specific package or new configurations for do the kernel compilation.

To modify the dockerfiles who do the compilation of the linux kernel you should modify the file :
./docker_management/settings_image_tuxml.py

If you don't know Dockerfile, you should follow a part of the docker documentation :
Dockerfile reference

What is the mains sections of code ?

• main script : ./kernel_generator.py
  • start docker container with specified options
• docker configuration : ./docker_management/
  • dockerfiles ./docker_management/settings_image_tuxml.py
  • script who manage docker images ./docker_management/docker_image_tuxml.py
• kernel compilation : ./compilation/
  • main script who do compilation ./compilation/main.py
    • compile
    • generate json data to send
  • send to the API ./compilation/apiManager.py
    • specify method to be connect to the TuxML API
• scripts bash : ./script_bash/
  • tests
  • generate images
  • flush data

How to debug inside a running TuxML container ?

If you need to try some manual kernel compilation or to test specific part of your developpement, it will be usefull to go inside a docker container of TuxML for run the commands who need :

docker run -it tuxml/tuxml-gcc6:dev

You can also copy file inside the container by docker command (check the documentation of docker for more examples) : ~$ docker cp <file> <container-id>:/<rest of the path>

Example :

~$ docker ps
CONTAINER ID        IMAGE                  COMMAND             CREATED             STATUS              PORTS               NAMES
213ef20be8ab        tuxml/tuxml-gcc6:dev   "bash"              24 seconds ago      Up 23 seconds                           funny_keller 
~$ docker cp test.py 213ef20be8ab:/source/test.py

Others

_{Last update : 2018-2019 Here is our code recovery manual. You will find an overview as well as information on our tools and scripts, and the operation of the project}