-
Notifications
You must be signed in to change notification settings - Fork 54
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
FEATURE: Add documentation for EMCApplication
Adding short documentation for EMCApplication local building. With procedures for native building of Debian packages in Docker environment (both native architecture and foreign) and building RIP.
- Loading branch information
Showing
4 changed files
with
217 additions
and
58 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,63 @@ | ||
| --- | ||
| --- | ||
|
|
||
| :skip-front-matter: | ||
|
|
||
| These instructions assume that you have `sudo` rights and that you can execute `bash` scripts on your machine. You will need to install these programs to follow the instructions to build (and develop) Machinekit organization's project. These programs were chosen to make the workflow easier and cleaner for the everybody, however if you were to choose to, you don't neccessarily need them. But support given through Machinekit channels expect you to have these installed. | ||
|
|
||
| As a first step make sure you can execute *Docker CLI* commands by installing https://docker.com[Docker]. The current steps needed for your platform are published in the official https://docs.docker.com/get-docker/[Docker documentation]. For the vast majority of cases following the Debian Buster (current Debian stable version) https://docs.docker.com/get-docker/[here] will be the right one. Make sure you can run Docker commands without the need for `sudo` command! | ||
|
|
||
| Test the installation by running few basic commands: | ||
|
|
||
| [source,bash] | ||
| ---- | ||
| machinekit@machinekit:~$ docker --version | ||
| Docker version 0.0.0-20190727010531-15bdbd76a5, build 15bdbd76a5 | ||
| machinekit@machinekit:~$ docker run hello-world | ||
| Unable to find image 'hello-world:latest' locally | ||
| latest: Pulling from library/hello-world | ||
| 1b930d010525: Pull complete | ||
| Digest: sha256:fc6a51919cfeb2e6763f62b6d9e8815acbf7cd2e476ea353743570610737b752 | ||
| Status: Downloaded newer image for hello-world:latest | ||
| Hello from Docker! | ||
| This message shows that your installation appears to be working correctly. | ||
| To generate this message, Docker took the following steps: | ||
| 1. The Docker client contacted the Docker daemon. | ||
| 2. The Docker daemon pulled the "hello-world" image from the Docker Hub. | ||
| (amd64) | ||
| 3. The Docker daemon created a new container from that image which runs the | ||
| executable that produces the output you are currently reading. | ||
| 4. The Docker daemon streamed that output to the Docker client, which sent it | ||
| to your terminal. | ||
| To try something more ambitious, you can run an Ubuntu container with: | ||
| $ docker run -it ubuntu bash | ||
| Share images, automate workflows, and more with a free Docker ID: | ||
| https://hub.docker.com/ | ||
| For more examples and ideas, visit: | ||
| https://docs.docker.com/get-started/ | ||
| machinekit@machinekit:~$ | ||
| ---- | ||
|
|
||
| Then you will need to have installed (and from terminal accessible) **git CLI**. The current steps needed for your platform are published in the official https://git-scm.com/book/en/v2/Getting-Started-Installing-Git[Git documentation]. For Debian system and standard official repository this means running: | ||
|
|
||
| [source,bash] | ||
| ---- | ||
| sudo apt install git | ||
| ---- | ||
|
|
||
| After test that you can successfully use git by running: | ||
|
|
||
| [source,bash] | ||
| ---- | ||
| machinekit@machinekit:~$ git --version | ||
| git version 2.27.0 | ||
| machinekit@machinekit:~$ | ||
| ---- |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,151 @@ | ||
| --- | ||
| --- | ||
|
|
||
| :skip-front-matter: | ||
|
|
||
| == [[packages-developing-rip]]Setting up for development | ||
| === [[packages-developing-docker]]Docker .deb build | ||
|
|
||
| . <<install-development-packages-docker,Install packages required for building Debian packages with Docker>> | ||
| . <<get-source-and-build-docker,Get and build the Debian packages>> | ||
|
|
||
| === [[packages-developing-rip]]Run-In-Place build | ||
|
|
||
| . <<install-development-packages,Install packages required for building from source>> | ||
| . <<get-source-and-build,Get and build the source>> | ||
|
|
||
| == [[install-development-packages-docker]]Install packages required for building Debian packages with Docker | ||
|
|
||
| These instructions assume that you have `sudo` rights and that you can execute `bash` scripts on your machine. You can build the *EMCApplication* debian package this way which can be then installed on target machine by the `apt` utility. You will also need to have installed **Git** executable and for container specific instructions also **Docker CLI** and **Docker daemon**. Directions for both can be found in link:/docs/developing/common-developing[Set up common development environment for all Machinekit projects]. | ||
|
|
||
| EMCApplication is tightly tracking https:github.com/linuxCNC/linuxcnc[LinuxCNC@master] branch with minimal set of additional patches to use the Machinekit-HAL project. You can try to follow https://linuxcnc.org/docs/devel/html/[LinuxCNC'd documentation], but be aware that any part pertaining RuntimeAPI (RTAPI), Hardware Abstraction Layer (HAL) and most HAL modules and Python code will not be accurate as these components come from Machinekit-HAL package. | ||
|
|
||
| The supported distributions for which you can build _apt_ packages is the intersection of supported distribution of Machinekit-HAL and supported distributions for LinuxCNC. | ||
|
|
||
| Currently, Machinekit-HAL code stack is fully Python 3 ported, LinuxCNC code stack is made so both Python 2 and Python 3 are supported (with some parts [mainly GUI] requiring Python 2), however the Debian packaging recipes still support only Python 2 (this problem is being intensively worked on in https://github.com/LinuxCNC/linuxcnc/pull/943[PR#943]). This means that for building of successful packages the input version of _machinekit-hal_ and _machinekit-hal-dev_ packages have to be https://cloudsmith.io/~machinekit/repos/machinekit-hal/packages/?q=version%3A0.4.20868*[**0.4.20868**] maximum. | ||
|
|
||
| Following steps presume that you have cloned the EMCApplication repository to local folder and that you know the _UID_ and _GID_ of your user. | ||
|
|
||
| [source,bash] | ||
| ---- | ||
| git clone https://github.com/machinekit/emcapplication.git | ||
| id | ||
| ---- | ||
|
|
||
| Starting from current version of _Debian Buster_ image downloaded from DockerHUB (replace with version for which you want to build the packages), the following commands would be used for building: | ||
|
|
||
| [source,bash] | ||
| ---- | ||
| docker run -it --rm -v "$(pwd):/machinekit/emca" debian:buster bash -i | ||
| apt update | ||
| apt upgrade | ||
| apt install build-essential fakeroot devscripts equivs sudo curl python lsb-release apt-cudf | ||
| addgroup machinekit --gid 1000 | ||
| adduser machinekit --uid 1000 --gid 1000 | ||
| echo "machinekit ALL = (ALL) NOPASSWD: ALL" >> /etc/sudoers | ||
| chown -R machinekit:machinekit /machinekit | ||
| su machinekit | ||
| curl -1sLf \ | ||
| 'https://dl.cloudsmith.io/public/machinekit/machinekit/cfg/setup/bash.deb.sh' \ | ||
| | sudo -E bash | ||
| curl -1sLf \ | ||
| 'https://dl.cloudsmith.io/public/machinekit/machinekit-hal/cfg/setup/bash.deb.sh' \ | ||
| | sudo -E bash | ||
| cd /machinekit/emca | ||
| ./debian/configure machinekit-hal=0.4.20894-1.gitebe1344a0~$(lsb_release -cs) no-docs | ||
| mk-build-deps -irs sudo -t 'apt-cudf-get --solver aspcud -o Debug::pkgProblemResolver=0 -o APT::Install-Recommends=0' | ||
| dpkg-buildpackage -us -uc | ||
| cp ../*.deb . | ||
| exit | ||
| exit | ||
| ---- | ||
|
|
||
| At the end you will have several new **.deb** files in your folder. | ||
|
|
||
| You should replace `--gid 1000`s and `--uid 1000` with numbers which you got from `id` command in previous step. | ||
|
|
||
| As EMCApplication packages are pinning the version of Machinekit-HAL packages dependency to one specific version, we need to pass this version string to _debian/configure_ script as `debian/configure machinekit-hal=${VERSION}`. One can use either version available from one of accessible Debian repositories, or already installed version. | ||
|
|
||
| To determine which Machinekit-HAL packages are currently installed on the system, run: | ||
|
|
||
| [source,bash] | ||
| ---- | ||
| apt list --installed | grep machinekit | ||
| ---- | ||
|
|
||
| As standard Debian _mk-build-deps_ script with _apt_ manager cannot resolve build dependencies fixed to one particular version, we need to install _apt-cudf_ package to be able to choose different dependency solver. | ||
|
|
||
| LinuxCNC does not support **cross-building** of Debian packages, which is the reason why you will need to build the _EMCApplication_ natively. Because of time needed to build the whole application on _arm_ devices, the best course of action is to use _QEMU-user-static_ binaries for running the foreign architecture code on _amd64_ machine. There are multiple ways how to reach functional system: First, use https://github.com/multiarch/qemu-user-static[Multiarch/QEMU-user-static] Docker image (please heed advice in https://github.com/multiarch/qemu-user-static/issues/17#issuecomment-518660227[this] issue if you get `sudo` related problem), or Second, install the https://packages.debian.org/sid/qemu-user-static[qemu-user-static] Debian package (preferably the latest, _Sid_ version). | ||
|
|
||
| Then run the Docker container with specific architecture (here _arm32_): | ||
|
|
||
| [source,bash] | ||
| ---- | ||
| docker run -it --rm -v "$(pwd):/machinekit/emca" arm32v7/debian:buster bash -i | ||
| dpkg --print-architecture && uname -m | ||
| apt update | ||
| apt upgrade | ||
| apt install build-essential fakeroot devscripts equivs sudo curl python lsb-release apt-cudf | ||
| addgroup machinekit --gid 1000 | ||
| adduser machinekit --uid 1000 --gid 1000 | ||
| echo "machinekit ALL = (ALL) NOPASSWD: ALL" >> /etc/sudoers | ||
| chown -R machinekit:machinekit /machinekit | ||
| su machinekit | ||
| sudo apt install debian-keyring debian-archive-keyring apt-transport-https | ||
| curl -k 'https://dl.cloudsmith.io/public/machinekit/machinekit/cfg/gpg/gpg.A9B6D8B4BD8321F3.key' | sudo apt-key add - | ||
| curl -k https://dl.cloudsmith.io/public/machinekit/machinekit/cfg/setup/config.deb.txt?distro=$(lsb_release -is | tr "[:upper:]" "[:lower:]")\&codename=$(lsb_release -cs) | sudo tee -a /etc/apt/sources.list.d/machinekit-machinekit.list | ||
| curl -k 'https://dl.cloudsmith.io/public/machinekit/machinekit-hal/cfg/gpg/gpg.D35981AB4276AC36.key' | sudo apt-key add - | ||
| curl -k https://dl.cloudsmith.io/public/machinekit/machinekit-hal/cfg/setup/config.deb.txt?distro=$(lsb_release -is | tr "[:upper:]" "[:lower:]")\&codename=$(lsb_release -cs) | sudo tee -a /etc/apt/sources.list.d/machinekit-machinekit-hal.list | ||
| sudo apt update | ||
| cd /machinekit/emca | ||
| ./debian/configure machinekit-hal=0.4.20894-1.gitebe1344a0~$(lsb_release -cs) no-docs | ||
| mk-build-deps -irs sudo -t 'apt-cudf-get --solver aspcud -o Debug::pkgProblemResolver=0 -o APT::Install-Recommends=0' | ||
| dpkg-buildpackage -us -uc | ||
| cp ../*.deb . | ||
| exit | ||
| exit | ||
| ---- | ||
|
|
||
| Running Docker containers has a problem with _SLL/certificates/PGP_ (generally speaking there is some problem with _encryption_). This is why the previous example is using the manual installation of Debian registry instead of the automatic script like native build. (https://cloudsmith.io/~machinekit/repos/machinekit/setup/#formats-deb[Here] is the original procedure from Cloudsmith.) _Information why is this happening and how to solve this issue are greatly appreciated._ | ||
|
|
||
| All other notes mentioned with native build previously are also valid here. | ||
|
|
||
| == [[install-development-packages]]Install packages required for building Run-In-Place | ||
|
|
||
| Building EMCApplication to run as separate and isolated software bundle (known as a RIP build from LinuxCNC world) is not possible. In all cases the Machinekit-HAL will need to be installed onto the system in the form of Debian packages. | ||
| timeAPI to find them. (This condition could be circumvented with changing _loader_ rules.) | ||
|
|
||
| All that would be compiled and ruI to find them. (This condition could be circumvented with changing _loader_ rules.) | ||
|
|
||
| All that would be compiled and run from the given directory, will be the Enhanced Machine Controller and Graphical User Interfaces. | ||
|
|
||
| From root of the EMCApplication source directory run: | ||
|
|
||
| [source,bash] | ||
| ---- | ||
| apt install build-essential fakeroot devscripts equivs python lsb-release apt-cudf | ||
| curl -1sLf \ | ||
| 'https://dl.cloudsmith.io/public/machinekit/machinekit/cfg/setup/bash.deb.sh' \ | ||
| | sudo -E bash | ||
| curl -1sLf \ | ||
| 'https://dl.cloudsmith.io/public/machinekit/machinekit-hal/cfg/setup/bash.deb.sh' \ | ||
| | sudo -E bash | ||
| debian/configure machinekit-hal=0.4.20894-1.gitebe1344a0~$(lsb_release -cs) no-docs | ||
| mk-build-deps -irs sudo -t 'apt-cudf-get --solver aspcud -o Debug::pkgProblemResolver=0 -o APT::Install-Recommends=0' | ||
| cd src | ||
| ./autogen.sh | ||
| ./configure --with-hal=machinekit-hal | ||
| make -j$(nproc) | ||
| sudo make install | ||
| source ../scripts/rip-environment | ||
| linuxcnc | ||
| ---- | ||
|
|
||
| Now you should have a functioning Machinekit-HAL + EMCApplication installation. You will need to rerun `source ../scripts/rip-environment` code in each new terminal to populate the environment with correct values. | ||
|
|
||
| It is also viable to disallow _apt_ to upgrade the _machinekit-hal_ package to higher version: | ||
|
|
||
| [source,bash] | ||
| ---- | ||
| sudo apt-mark hold machinekit-hal | ||
| ---- |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters