LGPL guide

(DRAFT)

Introduction

This page is supposed to help you complying with RIOT's license (LPGLv2.1).

General remarks

The RIOT OS is licensed under the terms of the GNU Lesser General Public license version 2.1 (LGPLv2.1).

See the FAQ for reasons.

The license requires you to release all changes made to RIOT's codebase to be released under the same license. It does not require you to release your application code under LGPL.

Note that this guide assumes you want to distribute RIOT itself or an application/device based on/using RIOT. If your usage of RIOT is purely in-house, you are free to keep all changes to yourself.

Mixing licenses

LGPLv2.1 makes it, contrary to the GPL, possible to create combined works consisting of LGPLv2.1 code and code licensed under different licenses. It is very well possible, and one of the reasons why we chose LGPLv2.1, to create proprietary applications on top of RIOT, under the condition that all non-LGPL'ed code is published in a form that allows re-linking.

The license text says you must:

"6a) Accompany the work with the complete corresponding machine-readable source code for the Library including whatever changes were used in the work (which must be distributed under Sections 1 and 2 above); and, if the work is an executable linked with the Library, with the complete machine-readable "work that uses the Library", as object code and/or source code, so that the user can modify the Library and then relink to produce a modified executable containing the modified Library. (It is understood that the user who changes the contents of definitions files in the Library will not necessarily be able to recompile the application to use the modified definitions.)"

The important aspect is whether you change RIOT files, and/or add code which get's linked in.

Any changes to RIOT's files must be published under LGPLv2.1. That includes headers that are included by RIOT files when building your application.

Any additional code must be published in a way that allows re-linking. Source code is perfect, compiled object code is sufficient.

Common questions

Do I have to release my application code under LGPL?

No, but if you don't, you'll have to provide users of your application access to the compiled object files (see 6a) of LGPLv2.1 license). See "Creating compiled object files" on how to create them.

I have a driver whose source code cannot be released.

The license doesn't make a difference between application or driver code. See above.

We have added support for a custom board, do we need to publish this work?

While possible, it is probably impractical to add support for a platform without changing how RIOT's code get's compiled, unless you rewrite most of the support. A lot of RIOT hardware abstraction code needs include files that are board specific. If any RIOT file includes any header created by you, those headers need to be released under LGPLv2.1.

Which applications are likely to require changes to the RIOT sources?

Any application just using RIOT's APIs (like sock for networking, or accessing hardware using periph/*) usually doesn't need to change RIOT itself.

It might be necessary, though, to change the peripheral configuration of the RIOT board you're using, which can be found in boards//include/periph_conf.h. That is necessary e.g., if you'd like to use an UART peripheral as SPI instead of serial. While those changes are only minimal, you'd still need to publish those changes to the users of your application.

Adding a driver usually does not require changes to the RIOT core. Depending on the type of the driver, it might be convenient to re-use code from the core that initializes the driver, although doing that from within your proprietary code is fairly easy.

As seen in the last answer, creating support for a new board almost certainly requires changes to the core RIOT sources.

Creating compiled object files

If you adhere to RIOT's usual way of using "modules", it is fairly easy to provide these object files, as every module ends up as archive (.a) in the build directory, which contains exactly these compiled object files. In the final build step, all *.a get linked together to form the binary that gets flashed on a device, but the intermediate *.a files are not deleted. Those can be made available publicly. As they are compiled code, releasing them is equivalent (in terms of source code disclosure) to releasing a firmware binary. Your code stays private.

Example

For your application, create a folder containing these files:

./Makefile:

APPLICATION = my_app

# If no BOARD is found in the environment, use this default:
BOARD ?= native

# This has to be the absolute path to the RIOT base directory:
RIOTBASE ?= /path/to/riot

DIRS += src
USEMODULE += my_proprietary_app

include $(RIOTBASE)/Makefile.include

src/Makefile:

MODULE = my_proprietary_app
include $(RIOTBASE)/Makefile.base

src/main.c:

#include "stdio.h"
int main(void) {
    printf("hello proprietary\n");
    return 0;
}

Check out your desired RIOT version to /path/to/riot.

This should build fine as is. Develop your application as usual. Create any proprietary modules in subfolders in src/, adding them to "DIRS" in src/Makefile.

Now, if you comment "DIRS += src", a clean build (make clean all) fails at the linking stage, missing "my_proprietary_app.a". Uncomment "DIRS += src", compile ("make all"), save bin//my_proprietary_app.a somewhere, run "make clean", copy the saved my_proprietary_app.a to "bin/", comment "DIRS += src", compile again ("make all" without clean). Now the build should succeed, but now using the precompiled my_proprietary_app.a.

(This seems clumsy, but is also easily scriptable. We'll add more automation soon.)

If you have added more modules to src/, those archives would also need to be saved.

If you now publish the Makefile together with my_proprietary_app.a (and any other archives of your proprietary modules), everyone can compile RIOT, link to your compiled proprietary code and generate a new binary.

This way, you're complying to LGPLv2.1, but don't have to provide the source code to your modules.

If you have to make changes to the RIOT tree (specified in RIOTBASE), those changes probably have to be released under LGPLv2.1.

Obviously you cannot copy files from $RIOTBASE into src/, modify them and use your copies. Also, if anything from $RIOTBASE includes files from src/, those include files also need to be published under LGPLv2.1.