sdk/licensedigger/README.md

0001 # License-Digger
0002
0003 This little tool helps to convert a project of source code files with traditional licenses headers to use statements that use the modern SPDX expressions.
0004 The tool allows to perform one time conversions, as well as to rerun it on a codebase later on to catch newly added files.
0005
0006 ## Out of Scope
0007
0008 The tools goal is only the _conversion_ of license headers. This means, explicitly the following features are not in scope (even though some are supported by accident):
0009
0010 - Linting the correctness of license statements your project. Use the `reuse lint` tool for this task.
0011 - Generate an overview of used licenses in your project. `reuse spdx` might be your answer.
0012 - Evaluating the outbound license of your compiled binaries. This is a difficult task with separate tooling.
0013
0014 ## Usage
0015
0016 Simply run `licensedigger <your-project-root-directory>`. You will be presented the detected licenses and be asked if you want to proceed with the conversion.
0017 For more options, see `licensedigger -h`.
0018
0019 ### Trouble Shooting
0020
0021 #### Not all licenses are converted!
0022
0023 Due to its design, license digger is not guessing any licence but detects it only if it matches exactly (except white-spaces and asterisks) with a license statement from the internal license database.
0024 You can easily add a new license to the database by the following steps:
0025
0026 1. Create a folder (in case it does not exist yet) in folder `licenses_templates/` that is named exactly as the target SPDX expression for the license header that you want to add. All white-spaces have to be replaced by underbars.
0027 2. In that folder create a text file that contains the license header that you want to add. It must not contain any comments or indentations.
0028 3. Edit `licenses.qrc` and add the newly created file.
0029 4. If you added a completely new license, add the canonical license text to `licensetexts/` and also add this file in `licenses.qrc`.
0030 5. Please use any source code that contains your new license header and add it to the unit tests (similar steps: add it to the correct `autotests/testsdata/` subfolder, edit `testdata.qrc`, modify the `headerdetection` unit test in case you added a new license.
0031 6. Execute all tests in the build folder `ctest -R`.
0032
0033 #### Copyright statements are converted incorrectly!
0034
0035 Most copyright statements should be detected and converted correctly. If you have problematic cases, please fill an issue and add the original copyright statement.
0036 All kinds of supported copyright statements are tested in the `copyrightconvert` unit test, in case you want to work on it yourself.
0037
0038 #### How can I cleanup asterisks and other cruft from the license statements?
0039
0040 Sorry, nothing is implemented yet, but patches are welcome :)
0041
0042 ## Base Design Decisions
0043
0044 The ultimate goal of license digger is to ensure zero false license conversions. For this goal, other reasonable architecture goals are negatively affected.
0045 For example:
0046
0047 - License statement files are added to the project by stating the containing license twice (naming in resource files and location of the license file) to minimize the likelihood of copy-paste errors.
0048 - The scope of regular expressions for detecting license variants is very small per license (mostly comment markers and white-space). This means, for every tiny license variation a separate license statement file has to be added.