how-to-build.rst 4.26 KB
Newer Older
Rahix's avatar
Rahix committed
1
2
3
4
5
6
7
8
9
10
11
How To Build
============
If you just want to write MicroPython code for card10, you probably **won't**
need to build the firmware yourself.  This page is for people who want to work
on the underlying firmware itself.

Dependencies
------------
* **gcc**, **binutils** & **newlib** for ``arm-none-eabi``:  The packages have
  slightly different names on different distros.

12
13
14
15
16
17
18
19
20
21
22
  - Ubuntu / Debian:

    .. code-block:: shell-session

       apt install gcc-arm-none-eabi binutils-arm-none-eabi libnewlib-arm-none-eabi

  - Arch:

    .. code-block:: shell-session

       pacman -S arm-none-eabi-gcc arm-none-eabi-binutils arm-none-eabi-newlib
Rahix's avatar
Rahix committed
23

torben's avatar
torben committed
24
  - Fedora
Rahix's avatar
Rahix committed
25

torben's avatar
torben committed
26
    .. code-block:: shell-session
Rahix's avatar
Rahix committed
27

torben's avatar
torben committed
28
        dnf install arm-none-eabi-gcc arm-none-eabi-binutils arm-none-eabi-newlib
29

Rahix's avatar
Rahix committed
30
31
  - Alternative: Download `ARM's GNU toolchain`_.  **TODO**
* **python3**:  For meson and various scripts needed for building.
Rahix's avatar
Rahix committed
32
* **meson** (>0.43.0) & **ninja**:  Unfortunately most distros only have very old versions
Rahix's avatar
Rahix committed
33
  of meson in their repositories.  Instead, you'll probably save yourself a lot
Rahix's avatar
Rahix committed
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
  of headaches by installing meson from *pip*.

   - Ubuntu / Debian:

    .. code-block:: shell-session

       apt install ninja-build
       pip3 install --user meson

   - Arch (has latest *meson* in the repos):

    .. code-block:: shell-session

       pacman -S meson

Rahix's avatar
Rahix committed
49
* **python3-crc16**: Install with ``pip3 install --user crc16``.
50
* **python3-pillow**: Python Image Library ``pip3 install --user pillow``.
Rahix's avatar
Rahix committed
51
52
53

.. _ARM's GNU toolchain: https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads

54
55
Cloning
-------
Rahix's avatar
Rahix committed
56
Clone the ``master`` branch of the firmware repository:
57
58
59
60
61

.. code-block:: shell-session

   $ git clone https://git.card10.badge.events.ccc.de/card10/firmware.git

Rahix's avatar
Rahix committed
62
63
64
Build Configuration
-------------------
Initialize the build-system using
Rahix's avatar
Rahix committed
65
66
67
68
69

.. code-block:: shell-session

   $ ./bootstrap.sh

Rahix's avatar
Rahix committed
70
71
72
Additional arguments to ``bootstrap.sh`` will be passed to *meson*.  You can
use this to for example, to enable one or more of the following optional
firmware features:
Rahix's avatar
Rahix committed
73

Rahix's avatar
Rahix committed
74
75
76
- ``-Ddebug_prints=true``: Print more verbose debugging log messages
- ``-Dble_trace=true``: Enable BLE tracing.  This will output lots of status
  info related to BLE.
77
78
- ``-Ddebug_core1=true``: Enable the core 1 SWD lines which are exposed on the
  SAO connector.  Only use this if you have a debugger which is modified for core 1.
Rahix's avatar
Rahix committed
79
80
81

.. warning::

Rahix's avatar
Rahix committed
82
83
84
85
86
87
   Our build-system contains a few workarounds around short-comings in meson.
   These workarounds might break on some setups which we did not yet test.  If
   this is the case for you, please open an issue in our `issue tracker`_!

.. _issue tracker: https://git.card10.badge.events.ccc.de/card10/firmware/issues

Rahix's avatar
Rahix committed
88
89
90
91
92
93
94
95
96
97
98
99
Building
--------
Build using *ninja*:

.. code-block:: shell-session

   $ ninja -C build/

If ninja succeeds, the resulting binaries are in ``build/``.  They are
available in two formats:  As an ``.elf`` which can be flashed using a debugger
and as a ``.bin`` which can be loaded using the provided bootloader.  Here is a
list of the binaries:
Rahix's avatar
Rahix committed
100
101
102
103
104
105

- ``build/bootloader/bootloader.elf``: Our bootloader.  It should already be on
  your card10.  The bootloader can only be flashed using a debugger.
- ``build/pycardium/pycardium_epicardium.bin``: The entire firmware in one ``.bin``.
- ``build/epicardium/epicardium.elf``: The core 0 part of the firmware, called Epicardium.
- ``build/pycardium/pycardium.elf``: Our MicroPython port, the core 1 part of the firmware.
106
107
108
109
110
111

In order to do a rebuild you can issue a clean command to ninja via

.. code-block:: shell-session

  $ ninja -C build/ -t clean
Rahix's avatar
Rahix committed
112
113

Otherwise, rerunning ``./bootstrap.sh`` will also clean the build-directory.
Kai's avatar
Kai committed
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135

Docker
======
Alternatively, clone the ``master`` branch of the firmware repository and enter it:

.. code-block:: shell-session

   $ git clone https://git.card10.badge.events.ccc.de/card10/firmware.git
   $ cd firmware

Afterwards, build a docker-container which will build the firmware via:

.. code-block:: shell-session

   $ docker build -f Dockerfile_fwbuild -t card10-firmware-builder .

Now, you can start the container with the firmware directory mounted, which will build the 
firmware into the firmware/build directory:

.. code-block:: shell-session

   $ docker run -v $(pwd):/firmware card10-firmware-builder