.. _install: Build & Install =============== The |project_name| server software is to be cross compiled for the ZC706 [#ZC706]_ board. Therefore a cross compiler is needed. The following sections describes all requirements and steps to install. Requirements ------------ The server software is build within a linux system. Since we build the software not directly on the ZC706 we have to cross-compile for the Arm [#arm_ref]_ platform. To do this the following requirements must be met: * This repository * *CMake* [#cmake_ref]_ - build system used by the server software * needed libraries have to be installed on the ZC706 * GCC cross compiler * Copy of parts of the root filesystem (*rootfs*) * (optional) automatic SSH access to ZC706 via public key Clone repository ~~~~~~~~~~~~~~~~ Clone the repository to your local machine and initialize the submodules. .. code-block:: shell git clone git@gitlab.mn.tu-dresden.de:wket/hardware/fpga-zc706/zc706-server.git git submodule update --init Install CMAKE ~~~~~~~~~~~~~ To install *CMake* in an Ubuntu system run the following: .. code-block:: shell apt install cmake Install needed libraries on the ZC706 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ZC706 needs the *build-essential* package to be installed. Therefore SSH into the ZC706 and install the package using root rights. .. code-block:: shell ssh debian@ZC706.local After that you can install the package. .. code-block:: shell sudo apt install build-essential For some reasons some symbolic links of libraries are absolute. This is a problem when trying to cross compile. Therefore we need to fix it using the *symlinks* tool .. code-block:: shell sudo apt install symlinks cd /usr/lib/arm-linux-gnueabihf sudo symlinks -rc . Another thing which needs to be done ist the following: .. code-block:: shell cd /usr/lib sudo ln -s arm-linux-gnueabihf/crt1.o crt1.o sudo ln -s arm-linux-gnueabihf/crti.o crti.o sudo ln -s arm-linux-gnueabihf/crtn.o crtn.o cd arm-linux-gnueabihf sudo ln -s libstdc++.so.6 libstdc++.so This is needed so that all libraries are found when building the software. The last thing to do on the ZC706 is to create the directory which should contain the server application. .. code-block:: shell mkdir -p ~/app GCC cross compiler ~~~~~~~~~~~~~~~~~~ A cross compiler tool chain may be found at `developer.arm.com `_. On the currently used system at the AKR-2 [#AKR_2]_ the version `arm-gnu-toolchain-12.3.rel1-x86_64-arm-none-linux-gnueabihf `_ is used. Make sure you use the *arm-none-linux-gnueabihf* architecture as this is the one running on the ZC706. To install it simply download it and extract to where ever you like. I suggest within ``~/tools/arm-cross-compiler``. Copy parts of the rootfs ~~~~~~~~~~~~~~~~~~~~~~~~ The cross compiler needs to know the libraries and includes of the ZC706 to compile and link the final binary. Therefore it is needed to copy those parts of the *rootfs* from the ZC706 to your system. The tool of choice to sync your copy of the *rootfs* with the ZC706 is the command *rsync* **which must be installed on both systems. The ZC706 and the host PC.** .. code-block:: shell sudo apt install rsync After sync the *usr* and the *lib* directory of the ZC706. It is assumed that the ZC706 is reachable using the hostname *nexmess.local*. Additionally it is assumed the rootfs should be installed to ``~/tools/ZC706/rootfs``. .. code-block:: shell mkdir ~/tools/ZC706/rootfs rsync -rl --delete-after --safe-links debian@nexmess.local:/{lib,usr} ~/tools/ZC706/rootfs This may take some time. Automatic SSH access to ZC706 via public key (optional but recommend) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When using a public key it is possible to directly access the ZC706 via SSH without having to enter a password. This makes it easy for the build system to directly copy the final binary onto the ZC706. If you have not done so already generate a key pair (without passphrase): .. code-block:: shell ssh-keygen -t ed25519 -C "your-mail@example.com" Copy the public key to the *authorized_keys* file of the ZC706. .. code-block:: shell ssh -T debian@ZC706 'mkdir -p ~/.ssh' cat ~/.ssh/id_ed25519.pub | ssh -T debian@ZC706 'cat >> ~/.ssh/authorized_keys' Now you should be able to access the ZC706 without entering a password. You may want to try it: .. code-block:: shell ssh debian@nexmess.local Assumptions ----------- This page assumes that the ZC706 is completely configured and running. It is assumed the ZC706 runs a Debian [#Debian_ref]_ system. Environment variables --------------------- This wiki pages uses environment variables to point to special directories. You don't have to set them but it makes almost all shown code copyable. - PROJECT_DIR - directory of the local copy of the git project. - ROOTFS_DIR - directory of the the copied *rootfs* of the ZC706 - CROSS_COMPILER_DIR - directory of the cross compiler Here is an example on how to set the variables. .. code-block:: shell export PROJECT_DIR=~/projects/daq3zc706-server export ROOTFS_DIR=~/tools/ZC706/rootfs export CROSS_COMPILER_DIR=~/tools/arm-cross-compiler/arm-gnu-toolchain-12.3.rel1-x86_64-arm-none-linux-gnueabihf .. _install-build-server-software: Build the server software ------------------------- As already mentioned the server software uses *CMake* to make things easy. It is also possible to directly copy the final binary onto the ZC706 in the correct directory. Before building the software clone it from the git repository. .. code-block:: shell git clone git@gitlab.mn.tu-dresden.de:wket/hardware/fpga-zc706/zc706-server.git git submodule update --init Configure the project ~~~~~~~~~~~~~~~~~~~~~ The project of the server software comes with a configuration example. Copy it to set your configuration. .. code-block:: shell cd $PROJECT_DIR cp config/config.cmake.example config/config.cmake Now edit the file to fit your needs. The following code snippet shows an example of changed settings within the config to match this wiki page. .. code-block:: cmake # ..... set(sysroot_base_path $ENV{HOME}/tools/ZC706/rootfs) set(toolchain_path $ENV{HOME}/tools/arm-cross-compiler/arm-gnu-toolchain-12.3.rel1-x86_64-arm-none-linux-gnueabihf) # ssh copy config # this only works if you can log in on the target device without password (via public key) # set ssh_copy to FALSE to turn this off # set ssh_auto_restart to FALSE to not automatically restart the service set(ssh_copy TRUE) set(ssh_auto_restart_service TRUE) set(ssh_user debian) set(ssh_host zc706) set(ssh_target_dir /home/debian/app) # ..... You can see that the *rootfs* directory is set to *sysroot_base_path*, the cross compiler directory is set to *toolchain_path* and that user specific settings for the ZC706 are made. When settings *ssh_copy* to *TRUE* the finished binary is directly copied to the ZC706 in the set directory (``/home/debian/app`` in this case). To make this possible you must be able to `access the ZC706 without credentials <#automatic-ssh-access-to-ZC706-via-public-key-optional-but-recommend>`_. When setting *ssh_auto_restart_service* to true the service is automatically stopped before copying the software to the ZC706. After copying the service will start again automatically. To be able to do that you must `configure the software as service <#start-server-software-automatically-on-boot>`_ and `allow the *debian* user to restart the service without password <#allow-user-to-restart-service>`_. Build the software ~~~~~~~~~~~~~~~~~~ There are two simple scripts to compile the project. * `compile_debug` - Compiles the debug version of the server software * `compile_release` - Compiles the release version of the server software Simply run one of the scripts and the software is build and depending on the configuration copied to the ZC706. The following snippet shows how to compile the release version. .. code-block:: shell ./compile_release Start server software automatically on boot ------------------------------------------- When actually planning to do measurements using the whole system it is wise to not bother with the ZC706 at all. So the server software should start automatically. Like this the measurements may start as soon as the green LED lights up. To do this *systemd* [#systemd_ref]_ is used. Therefore a *.service* script must be placed into */etc/systemd/system*. The project provides scripts for *akr2daq3*. So all you have to do is to copy them onto ZC706. You need *root* rights to do this so it has to be done in more than one step. First copy the script onto the ZC706. .. code-block:: shell scp $PROJECT_DIR/scripts/systemctl/akr2daq3.service debian@ZC706.local:/tmp/ Once the file is copied SSH into the ZC706 and log yourself in. Then switch to the root user using `sudo su` and do he following: .. code-block:: shell nano /tmp/akr2daq3.service Set the correct path for *ExecStart*. Save and close the file (CTRL+O -> CTRL+X). Then: .. code-block:: shell mv /tmp/akr2daq3.service /etc/systemd/system/ systemctl enable akr2daq3.service You may control the server software using the following commands if you feel there is a need for it: .. code-block:: shell systemctl start akr2daq3.service systemctl stop akr2daq3.service systemctl restart akr2daq3.service Assuming the server software is **not** running you can test if everything is fine by starting the software using the *start* command. The green LED should turn on. It should turn off again if you use the *stop* command. The green LED should turn on after about 30s after booting the ZC706. Allow user to restart service ----------------------------- When following the previous section it is a good idea to allow the *debian* user to restart the service, too. To du that login as *root* and run the following command: .. code-block:: shell visudo Add the following lines at the end of the file: .. code-block:: shell debian ALL=(ALL:ALL) NOPASSWD: /bin/systemctl start akr2daq3 debian ALL=(ALL:ALL) NOPASSWD: /bin/systemctl stop akr2daq3 debian ALL=(ALL:ALL) NOPASSWD: /bin/systemctl restart akr2daq3 Like this you can simply control the server as the *debian* user using *sudo* without any password. It is possible to automatically upload and restart the service when `building the server software <#build-the-software>`_, too. Build the documentation ----------------------- The documentation is automatically build on each push to the *main* branch. You can also build it manually. The documentation requires *Doxygen* [#doxygen_ref]_ and *Python* [#python_ref]_ to be installed on your system. To install it run the following command: .. code-block:: shell sudo apt install doxygen python3 Then you can build the documentation running the script `make_doc`: .. code-block:: shell ./make_doc The documentation will be available within the ``html`` directly. Bibliography ------------ .. [#ZC706] `AMD Zynq 7000 SoC ZC706 Evaluation Kit `_ .. [#arm_ref] `Arm `_ .. [#cmake_ref] `CMake `_ .. [#AKR_2] `AKR-2 `_ .. [#Debian_ref] `Debian `_ .. [#systemd_ref] `systemd `_ .. [#doxygen_ref] `Doxygen `_ .. [#python_ref] `Python `_