lets have another look

readme.md

@@ -16,6 +16,8 @@ The ``colorCommand`` accepts one, two, three or four arguments. With only one ar
 
 The ``build-env-arduino`` docker image, which can be loaded using the image name ``registry.gitlab.com/wolutator/build-env-arduino:latest`` is a tinned or preserved build environment for boards supported by the Arduino development system. Currently ``arduino:avr`` and ``esp8266:esp8266`` are supported by this image.
 
+It is maintained in to the project [https://gitlab.com/wolutator/build-env-arduino].
+
 A preserved build environment, which easily can be installed or simply loaded for many developers in exactly the same way and which can easily be archived is a major topic is professional software engineering. If you have a team of lots of developers you don't want to waste time by letting everyone install his or her development environment manually, finally ending up with minor to major differences which makes it hard to compare or integrate software or let one developer investigate a bug another developer found. Furthermore you want to be able, especially in an industrial environment, to pick a development environment from the shelve to investigate and fix an issue reported in a years-old software. Both can be achieved with preserved environments.
 
 This preserved Arduino build environment uses the Arduino CLI tool, which can be found at [https://downloads.arduino.cc/arduino-cli/arduino-cli-latest-linux64.tar.bz2] and which is discussed here [https://blog.arduino.cc/2018/08/24/announcing-the-arduino-command-line-interface-cli/].
@@ -29,6 +31,8 @@ So, I created the following directory structure of my project repository:
     +--- sketch/
     |    |
     |    +--- sketch.ino
+    |    +--- application.cpp
+    |    +--- application.h
     |
     +--- libraries/
     |    |
@@ -46,3 +50,25 @@ To make the Arduino CLI use this structure, I point the variable ``ARDUINO_SKETC
 
     env ARDUINO_SKETCHBOOK_DIR=$PROJECT_DIR arduino-cli compile --fqbn=esp8266:esp8266:nodemcu $PROJECT_DIR/sketch
 
+The Arduino system expects a file with the extension ``.ino`` and same name as the directory within the sketchbook directory. Since in my setup every project lifes in a separate sketchbook directory, I call the directory with the main application sources ``sketch`` and the accordingly the ``ino``-file ``sketch.ino``. This file contain the typical main functions of each Arduino project, which are ``setup`` and ``loop``.
+
+In my projects, I do not put any meaningful code into the ``ino``, I have everything in the companion ``cpp`` file, which is usually ``application.cpp`` (with its friend ``application.h``)
+
+When the Arduino system trys to find some included ``.h`` it has a powerful strategy, which works without any ``CFLAGS`` variable with ``-I`` options. It works just by convention. Thus, it searches in the Arduino core folders, in the ``sketch`` folder itself and in all subfolders of the ``libraries`` folder. For this reason I put a ``includes`` folder into the ``libraries`` folder where I place all header files, which are shared between the main application (the "sketch") and some libraries.
+
+This approach can easily be implemented in a Gitlab CI script:
+
+    build:
+        stage: build
+        image: registry.gitlab.com/wolutator/build-env-arduino:latest
+        variables:
+                GIT_SUBMODULE_STRATEGY: recursive
+        artifacts:
+                paths:
+                        - sketch.esp8266.esp8266.nodemcu.bin
+        script:
+                - env ARDUINO_SKETCHBOOK_DIR=$CI_PROJECT_DIR arduino-cli compile --fqbn=esp8266:esp8266:nodemcu $CI_PROJECT_DIR/sketch
+                - cp sketch/sketch.esp8266.esp8266.nodemcu.* .
+
+
+