From: Francis Dupont Date: Thu, 16 Jul 2020 20:22:46 +0000 (+0200) Subject: [#1221] Added cross-compile doc X-Git-Tag: Kea-1.7.10~28 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=bc4a33ee8b4ef3a2126ed4fc6aa6528c239a361a;p=thirdparty%2Fkea.git [#1221] Added cross-compile doc --- diff --git a/ChangeLog b/ChangeLog index c199f6201b..34200833a7 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +1777. [doc] fdupont + Added in the Developer's Guide an example about how to cross + compile Kea for a Raspberry Pi. + (Gitlab #1221) + 1776. [func] fdupont DHCP servers now log a fatal error message when a reconfiguration attempt left a no longer working server. Documentation was diff --git a/doc/devel/Makefile.am b/doc/devel/Makefile.am index 62ff245492..9b740be71b 100644 --- a/doc/devel/Makefile.am +++ b/doc/devel/Makefile.am @@ -4,6 +4,7 @@ EXTRA_DIST += bison.dox EXTRA_DIST += config-backend.dox EXTRA_DIST += congestion-handling.dox EXTRA_DIST += contribute.dox +EXTRA_DIST += cross-compile.dox EXTRA_DIST += doc.dox EXTRA_DIST += fuzz.dox EXTRA_DIST += mainpage.dox diff --git a/doc/devel/cross-compile.dox b/doc/devel/cross-compile.dox new file mode 100644 index 0000000000..4244ba4d13 --- /dev/null +++ b/doc/devel/cross-compile.dox @@ -0,0 +1,226 @@ +// Copyright (C) 2020 Internet Systems Consortium, Inc. ("ISC") +// +// This Source Code Form is subject to the terms of the Mozilla Public +// License, v. 2.0. If a copy of the MPL was not distributed with this +// file, You can obtain one at http://mozilla.org/MPL/2.0/. + +/** + + @page crossCompile Kea Cross-Compiling Example + +The idea is to install Kea on a Raspberry Pi 4 Model B running Raspbian +operation system (e.g. the + +Raspbian Buster with desktop and recommended software distribution) +without having to compile Kea on the Raspberry Pi box itself as it +takes some hours so using a standard Linux box with a x86_64 processor. + +To cross-compile anything for Raspbian you need: + - a cross-compiler running on x86_64 producing arm binaries + - either an image of system copied from a Raspberry disk or extracted + from a Raspbian repository. + +@section toolChain Cross-Compile Tool Chain + +A priori it is possible to compile your own tool chain or to use +a package as the arm-linux-gnueabihf one on Ubuntu. But there is +reported compatibility issue with old Raspberry Pi versions) so +we recommend a pre-built dedicated tool chain for this purpose: +. + +The documentation of this tool chain gives a rsync command which +copies selected parts of the Raspberry Pi root filesystem ("rootfs"). +If you have no access to a running Raspberry Pi it is still possible +to get them following next section instructions. If you have simply +skip this part. + +@section noRaspberry How to get system and packages without a running Raspberry Pi + +It is not required to have access to a running Raspberry Pi. +The system disk image is available at the Raspbian URL. +Packages are in the Raspian repository which is given in +sources list files in this disk image or below. + +The "sources.list" file content is: +@verbatim +deb http://raspbian.raspberrypi.org/raspbian/ buster main contrib non-free rpi +# Uncomment line below then 'apt-get update' to enable 'apt-get source' +# deb-src http://raspbian.raspberrypi.org/raspbian/ buster main contrib non-free rpi +@endverbatim + +and the "sources.list.d/raspi.list" file content is: +@verbatim +deb http://archive.raspberrypi.org/debian/ buster main +# Uncomment line below then 'apt-get update' to enable 'apt-get source' +# deb-src http://archive.raspberrypi.org/debian/ buster main +@endverbatim + +The disk image is a zipped image of a 4GB disk with a standard MSDOS +boot block with two volumes: + - boot (useless for this purpose) + - rootfs (the Raspberry Pi root filesystem) + +The idea is to mount the rootfs on the Linux box (it can work on another +system as soon as it supports the ext4 file system type): + - first use fdisk or similar tool to get the offset of the first block + of the rootfs (second) volume + - if the offset is in block unit multiply by 512 (block size) + - mount as root (sudo mount ...) with the loop option, the offset option, + the unzipped image file name and a mount point (absolute path of + a directory) +If you have a SD card with Raspbian installed on it and a SD reader +you can directly mount the rootfs from it. + +If a dependency (i.e. the Raspbian version of a library) is not in the +rootfs image you need to simulate its installation: + - get the .deb file from a Raspbian repository + - extract files using the "dpkg-deb -R" tool on the .deb file + - install the files (usually in the "rootfs"/usr directory) +The idea is the files (includes and libraries) can be find by +the cross-compiling tool chain. + +It is possible to emulate a Raspberry Pi using qemu even I do not think +it can run Kea. But at least it can run some tests as the hello world sample +of the tool chain. Required qemu kernels can be found at +" + +Known problems: + - AC_TRY_RUN and AC_CHECK_FILE[S] autoconf macros do not support + cross-compiling. They were removed from ./configure.ac in Kea 1.7.10. + - libtool is a disaster for cross-compiling, in particular it produces + silly libtool archive (.la) files. Fortunately they are useless. + - bad paths for mkdir or sed on Raspbian. + - recent Debian systems including recent Ubuntu modified libtool to + not accept indirect dependencies. Makefiles were updated to have no + such indirect dependencies in common cases as it is in Kea Makefile + writing guidelines. + - the libtool variable managing this is link_all_deplibs. You can + edit the libtool script to set it to unknown or yes. Or simply + use another Linux distrib. + - there is no ldd in cross-compiling tools. The table of used + shared libraries in available by readelf -d which is in the + cross-compiling tools. + +Final words: this is still highly experimental and does not cover +everything. New ways to offload almost everything outside the Raspberry +Pi are still to be found. Currently to provide Raspbian Kea packages +is not possible for ISC. + +*/ diff --git a/doc/devel/mainpage.dox b/doc/devel/mainpage.dox index c51eca4c97..b2ea570fba 100644 --- a/doc/devel/mainpage.dox +++ b/doc/devel/mainpage.dox @@ -148,6 +148,7 @@ * - @subpage LoggingApi * - @subpage SocketSessionUtility * - @subpage fuzzer + * - @subpage crossCompile * - @subpage docs * - Documentation warnings and errors * diff --git a/doc/sphinx/arm/install.rst b/doc/sphinx/arm/install.rst index 272cff941b..a230a65756 100644 --- a/doc/sphinx/arm/install.rst +++ b/doc/sphinx/arm/install.rst @@ -388,6 +388,19 @@ relevant linker cache configuration file for your OS): cannot open shared object file: No such file or directory +Cross-Building +-------------- + +It is possible to cross-build Kea, i.e. to create binaries in another +system (the ``build`` system) than the system where Kea will run +(the ``host`` system). + +It is outside of the scope of common administrator operations and requires +some developer skills so the Developer Guide explains how to do that +using a x86_64 Linux system to build Kea for a Raspberry Pi box running +Raspbian: `Kea Cross-Compiling Example +`__. + .. _dhcp-install-configure: DHCP Database Installation and Configuration