Adding External Sources
Having local copies of those modules brings some disadvantages with it:
We cannot easily update the local copy from the original source code.
We cannot easily send improvements to those projects once we make local changes in our local copy.
Sming uses GIT submodules which allows the build system to fetch source code from an external repository on demand.
If modifications are required then the submodule can be patched.
This simplifies the process of integrating changes from those third-party projects.
Where to place external code
The location must be chosen carefully:
Code required within the core Sming framework
If the Component supports multiple architectures, place it in
Sming/Components. Otherwise, use the appropriate
Code for general use
Create a new Library in
Please consult Sming build system for further details about how Components are constructed.
Copying Source Code
If the source code does not have a publicly accessible GIT repository then the source code needs to be copied locally.
In order to track changes more easily, the initial commit should be an exact copy of the original.
Please either comment the code or add notes to the documentation to detail any required changes for compatibility.
As an example, this is how the new PWM submodule was added to the Esp8266 Drivers Component:
Add the submodule using GIT:
cd $SMING_HOME git submodule add \ --name ESP8266.new-pwm \ https://github.com/StefanBruens/ESP8266_new_pwm.git \ Arch/Esp8266/Components/driver/new-pwm
This adds an entry to the end of the
path = Sming/Arch/Esp8266/Components/driver/new-pwm
url = https://github.com/StefanBruens/ESP8266_new_pwm.git
For naming submodules, please follow the convention used for the other entries in
.gitmodules, which is determined by the local path:
- ``Sming/Components``: just use the name of the submodule
- ``Sming/Arch/ARCH/Components``: Use ``ARCH.name``
- ``Sming/Libraries``: Use ``Libraries.name``
.gitmodulesin a text editor and:
Move the entry to a more suitable location in the file, i.e. at the end of the section listing all the ESP8266-specific submodules
Add the line
ignore = dirty
If a submodule requires changes to work with Sming, this can be handled using patches.
This is generally done by pulling in the original submodule, making the required changes
and then running a
diff to create a patch file, like this:
git diff --no-ext-diff > <module-name>.patch
If using a GUI such as GIT Extensions then this can be done using a right-click.
See GIT Submodules for further details about how patches are used and where they should be placed.
If the submodule is added as a Component in its own right, no further action is required. Applications can use it by adding the name to their COMPONENT_DEPENDS or ARDUINO_LIBARIES entries in component.mk as appropriate.
Submodules contained within a Component must be declared by adding them to the
COMPONENT_SUBMODULES entry in component.mk.
If you need to change the location of a submodule, here’s a suggested approach. In this example, we’re going to move the Adafruit_Sensor submodule into a Component:
# Move the submodule temporarily
Sming/Libraries$ git mv Adafruit_Sensor tmp
# Create our new Component directory
Sming/Libraries$ mkdir Adafruit_Sensor
# Move the submodule back as a sub-directory
Sming/Libraries$ git mv tmp Adafruit_Sensor/Adafruit_Sensor
Now we can add a component.mk file, README.rst, etc. as required for the component.