| Message ID | alpine.DEB.2.20.1711171057240.1709@nanos (mailing list archive) |
|---|---|
| State | Superseded, archived |
| Headers | show |
On Fri, Nov 17, 2017 at 11:00 AM, Thomas Gleixner <tglx@linutronix.de> wrote: > Subject: Documentation: Add license-rules.rst to describe how to properly identify file licenses > From: Thomas Gleixner <tglx@linutronix.de> > Date: Fri, 10 Nov 2017 09:30:00 +0100 > > Add a file to the Documentation directory to describe how file licenses > should be described in all kernel files, using the SPDX identifier, as well > as where all licenses should be in the kernel source tree for people to > refer to (LICENSES/). > > Thanks to Kate, Greg and Jonathan for review and editing and Jonas for the > suggestions concerning the meta tags in the licenses files. > > Signed-off-by: Thomas Gleixner <tglx@linutronix.de> > --- > > Changes since V3: > - Addressed Jonathans review comments > - Added .dts{i} syntax (Rob) > > --- For this V4 and all the V2 11 patch series, after using a fine comb.... Reviewed-by: Philippe Ombredanne <pombredanne@nexb.com>
On Fri, 17 Nov 2017, Kate Stewart wrote: > On Fri, Nov 17, 2017 at 4:00 AM, Thomas Gleixner <tglx@linutronix.de> wrote: > > + The files in this directory the full license text and `Metatags`_. > > > Missing verb. Possibly "contain"? > > The files in this directory contain the full license text and `Metatags`_. Yes. Fixed. > Feel free to add my > > Reviewed-by: Kate Stewart <kstewart@linuxfoundation.org> > > For this V4 and the other 11 patches. Thanks! tglx -- To unsubscribe from this list: send the line "unsubscribe linux-xfs" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Hi Thomas, Em Fri, 17 Nov 2017 11:00:33 +0100 (CET) Thomas Gleixner <tglx@linutronix.de> escreveu: > Subject: Documentation: Add license-rules.rst to describe how to properly identify file licenses > From: Thomas Gleixner <tglx@linutronix.de> > Date: Fri, 10 Nov 2017 09:30:00 +0100 > > Add a file to the Documentation directory to describe how file licenses > should be described in all kernel files, using the SPDX identifier, as well > as where all licenses should be in the kernel source tree for people to > refer to (LICENSES/). > > Thanks to Kate, Greg and Jonathan for review and editing and Jonas for the > suggestions concerning the meta tags in the licenses files. > > Signed-off-by: Thomas Gleixner <tglx@linutronix.de> The document itself looks good, but I think it should also mention what would be the expected values for the MODULE_LICENSE() macro and how each license would be mapped into it. Right now, include/linux/module.h says: /* * The following license idents are currently accepted as indicating free * software modules * * "GPL" [GNU Public License v2 or later] * "GPL v2" [GNU Public License v2] * "GPL and additional rights" [GNU Public License v2 rights and more] * "Dual BSD/GPL" [GNU Public License v2 * or BSD license choice] * "Dual MIT/GPL" [GNU Public License v2 * or MIT license choice] * "Dual MPL/GPL" [GNU Public License v2 * or Mozilla license choice] * * The following other idents are available * * "Proprietary" [Non free products] * * There are dual licensed components, but when running with Linux it is the * GPL that is relevant so this is a non issue. Similarly LGPL linked with GPL * is a GPL combined work. * * This exists for several reasons * 1. So modinfo can show license info for users wanting to vet their setup * is free * 2. So the community can ignore bug reports including proprietary modules * 3. So vendors can do likewise based on their own policies */ #define MODULE_LICENSE(_license) MODULE_INFO(license, _license) In thesis, for every SPDX property at C or assembler files, we should have a mapping into one of those MODULE_LICENSE(). > --- > > Changes since V3: > - Addressed Jonathans review comments > - Added .dts{i} syntax (Rob) > > --- > Documentation/index.rst | 12 + > Documentation/process/license-rules.rst | 370 ++++++++++++++++++++++++++++++++ > 2 files changed, 382 insertions(+) > create mode 100644 Documentation/license-rules.rst > > --- a/Documentation/index.rst > +++ b/Documentation/index.rst > @@ -13,6 +13,18 @@ documents into a coherent whole. Please > documentation are welcome; join the linux-doc list at vger.kernel.org if > you want to help out. > > +Licensing documentation > +----------------------- > + > +The following describes the license of the Linux kernel source code > +(GPLv2), how to properly mark the license of individual files in the source > +tree, as well as links to the full license text. > + > +.. toctree:: > + :maxdepth: 2 > + > + process/license-rules.rst > + > User-oriented documentation > --------------------------- > > --- /dev/null > +++ b/Documentation/process/license-rules.rst > @@ -0,0 +1,370 @@ > +.. SPDX-License-Identifier: GPL-2.0 > + > +Linux kernel licensing rules > +============================ > + > +The Linux Kernel is provided under the terms of the GNU General Public > +License version 2 only (GPL-2.0), as published by the Free Software > +Foundation, and provided in the COPYING file. This documentation file is > +not meant to replace the COPYING file, but provides a description of how > +each source file should be annotated to make the licensing it is governed > +under clear and unambiguous. > + > +The license in the COPYING file applies to the kernel source as a whole, > +though individual source files can have a different license which is > +required to be compatible with the GPL-2.0:: > + > + GPL-1.0+ : GNU General Public License v1.0 or later > + GPL-2.0+ : GNU General Public License v2.0 or later > + LGPL-2.0 : GNU Library General Public License v2 only > + LGPL-2.0+ : GNU Library General Public License v2 or later > + LGPL-2.1 : GNU Lesser General Public License v2.1 only > + LGPL-2.1+ : GNU Lesser General Public License v2.1 or later > + > +Aside from that, individual files can be provided under a dual license, > +e.g. one of the compatible GPL variants and alternatively under a > +permissive license like BSD, MIT etc. > + > +The User-space API (UAPI) header files, which describe the interface of > +user-space programs to the kernel are a special case. According to the > +note in the kernel COPYING file, the syscall interface is a clear boundary, > +which does not extend the GPL requirements to any software which uses it to > +communicate with the kernel. Because the UAPI headers must be includable > +into any source files which create an executable running on the Linux > +kernel, the exception must be documented by a special license expression. > + > +The common way of expressing the license of a source file is to add the > +matching boiler plate text into the top comment of the file. Due to > +formatting, typos etc. these "boiler plates" are hard to validate for > +tools which are used in the context of license compliance. > + > +An alternative to boilerplate text is the use of Software Package Data > +Exchange (SPDX) license identifiers in each source file. SPDX license > +identifiers are machine parsable and precise shorthands for the license > +under which the content of the file is contributed. SPDX license > +identifiers are managed by the SPDX Workgroup at the Linux Foundation and > +have been agreed on by partners throughout the industry, tool vendors, and > +legal teams. For further information see https://spdx.org/ > + > +The Linux kernel requires the precise SPDX identifier in all source files. > +The valid identifiers used in the kernel are explained in the section > +`License identifiers`_ and have been retrieved from the official SPDX > +license list at https://spdx.org/licenses/ along with the license texts. > + > +License identifier syntax > +------------------------- > + > +1. Placement: > + > + The SPDX license identifier in kernel files shall be added at the first > + possible line in a file which can contain a comment. For the majority > + or files this is the first line, except for scripts which require the > + '#!PATH_TO_INTERPRETER' in the first line. For those scripts the SPDX > + identifier goes into the second line. > + > +| > + > +2. Style: > + > + The SPDX license identifier is added in form of a comment. The comment > + style depends on the file type:: > + > + C source: // SPDX-License-Identifier: <SPDX License Expression> > + C header: /* SPDX-License-Identifier: <SPDX License Expression> */ > + ASM: /* SPDX-License-Identifier: <SPDX License Expression> */ > + scripts: # SPDX-License-Identifier: <SPDX License Expression> > + .rst: .. SPDX-License-Identifier: <SPDX License Expression> > + .dts{i}: // SPDX-License-Identifier: <SPDX License Expression> > + > + If a specific tool cannot handle the standard comment style, then the > + appropriate comment mechanism which the tool accepts shall be used. This > + is the reason for having the "/\* \*/" style comment in C header > + files. There was build breakage observed with generated .lds files where > + 'ld' failed to parse the C++ comment. This has been fixed by now, but > + there are still older assembler tools which cannot handle C++ style > + comments. > + > +| > + > +3. Syntax: > + > + A <SPDX License Expression> is either an SPDX short form license > + identifier found on the SPDX License List, or when multiple licenses > + apply, an expression consisting of keywords "AND", "OR", and "WITH" > + separating SPDX short form license identifiers surrounded by "(", ")". > + > + License identifiers for licenses like [L]GPL with the 'or later' option > + are constructed by using a "+" for indicating the 'or later' option.:: > + > + // SPDX-License-Identifier: GPL-2.0+ > + // SPDX-License-Identifier: LGPL-2.1+ > + > + WITH should be used when there is a modifier to a license needed. > + For example, the linux kernel UAPI files use the expression:: > + > + // SPDX-License-Identifier: (GPL-2.0 WITH Linux-syscall-note) > + // SPDX-License-Identifier: (GPL-2.0+ WITH Linux-syscall-note) > + > + Other examples using WITH exceptions found in the kernel are:: > + > + // SPDX-License-Identifier: (GPL-2.0 WITH mif-exception) > + // SPDX-License-Identifier: (GPL-2.0+ WITH GCC-exception-2.0) > + > + Exceptions can only be used with particular License identifiers. The > + valid License identifiers are listed in the tags of the exception text > + file. For details see the point `Exceptions`_ in the chapter `License > + identifiers`_. > + > + OR should be used if the file is dual licensed and only one license is > + to be selected. For example, some dtsi files are available under dual > + licenses:: > + > + // SPDX-License-Identifier: (GPL-2.0 OR BSD-3-Clause) > + > + Examples from the kernel for license expressions in dual licensed files:: > + > + // SPDX-License-Identifier: (GPL-2.0 OR MIT) > + // SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) > + // SPDX-License-Identifier: (GPL-2.0 OR Apache-2.0) > + // SPDX-License-Identifier: (GPL-2.0 OR MPL-1.1) > + // SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR MIT) > + // SPDX-License-Identifier: ((GPL-1.0+ OR BSD-3-Clause) OR OpenSSL) > + > + AND should be used if the file has multiple licenses whose terms all > + apply to use the file. For example, if code is inherited from another > + project and permission has been given to put it in the kernel, but the > + original license terms need to remain in effect:: > + > + // SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) AND MIT) > + > + Another other example where both sets of license terms need to be > + adhered to is:: > + > + // SPDX-License-Identifier: (GPL-1.0+ AND LGPL-2.1+) > + > +License identifiers > +------------------- > + > +The licenses currently used, as well as the licenses for code added to the > +kernel, can be broken down into: > + > +1. _`Preferred licenses`: > + > + Whenever possible these licenses should be used as they are known to be > + fully compatible and widely used. These licenses are available from the > + directory:: > + > + LICENSES/preferred/ > + > + in the kernel source tree. > + > + The files in this directory the full license text and `Metatags`_. > + > + The file names are identical to the SPDX license identifier which shall > + be used for the license in source files. > + > + Examples:: > + > + LICENSES/preferred/GPL-2.0 > + > + Contains the GPL version 2 license text and the required metatags:: > + > + LICENSES/preferred/MIT > + > + Contains the MIT license text and the required metatags > + > + _`Metatags`: > + > + The following meta tags must be available in a license file: > + > + - Valid-License-Identifier: > + > + One or more lines which declare which License Identifiers are valid > + inside the project to reference this particular license text. Usually > + this is a single valid identifier, but e.g. for licenses with the 'or > + later' options two identifiers are valid. > + > + - SPDX-URL: > + > + The URL of the SPDX page which contains additional information related > + to the license. > + > + - Usage-Guidance: > + > + Freeform text for usage advice. The text must include correct examples > + for the SPDX license identifiers as they should be put into source > + files according to the `License identifier syntax`_ guidelines. > + > + - License-Text: > + > + All text after this tag is treated as the original license text > + > + File format examples:: > + > + Valid-License-Identifier: GPL-2.0 > + Valid-License-Identifier: GPL-2.0+ > + SPDX-URL: https://spdx.org/licenses/GPL-2.0.html > + Usage-Guide: > + To use this license in source code, put one of the following SPDX > + tag/value pairs into a comment according to the placement > + guidelines in the licensing rules documentation. > + For 'GNU General Public License (GPL) version 2 only' use: > + SPDX-License-Identifier: GPL-2.0 > + For 'GNU General Public License (GPL) version 2 or any later version' use: > + SPDX-License-Identifier: GPL-2.0+ > + License-Text: > + Full license text > + > + :: > + > + SPDX-License-Identifier: MIT > + SPDX-URL: https://spdx.org/licenses/MIT.html > + Usage-Guide: > + To use this license in source code, put the following SPDX > + tag/value pair into a comment according to the placement > + guidelines in the licensing rules documentation. > + SPDX-License-Identifier: MIT > + License-Text: > + Full license text > + > +| > + > +2. Not recommended licenses: > + > + These licenses should only be used for existing code or for importing > + code from a different project. These licenses are available from the > + directory:: > + > + LICENSES/other/ > + > + in the kernel source tree. > + > + The files in this directory the full license text and `Metatags`_. > + > + The file names are identical to the SPDX license identifier which shall be > + used for the license in source files. > + > + Examples:: > + > + LICENSES/other/ISC > + > + Contains the Internet Systems Consortium license text and the required > + metatags:: > + > + LICENSES/other/ZLib > + > + Contains the ZLIB license text and the required metatags. > + > + Metatags: > + > + The metatag requirements for 'other' licenses are identical to the > + requirements of the `Preferred licenses`_. > + > + File format example:: > + > + Valid-License-Identifier: ISC > + SPDX-URL: https://spdx.org/licenses/ISC.html > + Usage-Guide: > + Usage of this license in the kernel for new code is discouraged > + and it should solely be used for importing code from an already > + existing project. > + To use this license in source code, put the following SPDX > + tag/value pair into a comment according to the placement > + guidelines in the licensing rules documentation. > + SPDX-License-Identifier: ISC > + License-Text: > + Full license text > + > +| > + > +3. _`Exceptions`: > + > + Some licenses can be amended with exceptions which grant certain rights > + which the original license does not. These exceptions are available > + from the directory:: > + > + LICENSES/exceptions/ > + > + in the kernel source tree. The files in this directory contain the full > + exception text and the required `Exception Metatags`_. > + > + Examples:: > + > + LICENSES/exceptions/Linux-syscall-note > + > + Contains the Linux syscall exception as documented in the COPYING > + file of the Linux kernel, which is used for UAPI header files. > + e.g. /\* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note \*/:: > + > + LICENSES/exceptions/GCC-exception-2.0 > + > + Contains the GCC 'linking exception' which allows to link any binary > + independent of its license against the compiled version of a file marked > + with this exception. This is required for creating runnable executables > + from source code which is not compatible with the GPL. > + > + _`Exception Metatags`: > + > + The following meta tags must be available in an exception file: > + > + - SPDX-Exception-Identifier: > + > + One exception identifier which can be used with SPDX license > + identifiers. > + > + - SPDX-URL: > + > + The URL of the SPDX page which contains additional information related > + to the exception. > + > + - SPDX-Licenses: > + > + A comma separated list of SPDX license identifiers for which the > + exception can be used. > + > + - Usage-Guidance: > + > + Freeform text for usage advice. The text must be followed by correct > + examples for the SPDX license identifiers as they should be put into > + source files according to the `License identifier syntax`_ guidelines. > + > + - Exception-Text: > + > + All text after this tag is treated as the original exception text > + > + File format examples:: > + > + SPDX-Exception-Identifier: Linux-syscall-note > + SPDX-URL: https://spdx.org/licenses/Linux-syscall-note.html > + SPDX-Licenses: GPL-2.0, GPL-2.0+, GPL-1.0+, LGPL-2.0, LGPL-2.0+, LGPL-2.1, LGPL-2.1+ > + Usage-Guidance: > + This exception is used together with one of the above SPDX-Licenses > + to mark user-space API (uapi) header files so they can be included > + into non GPL compliant user-space application code. > + To use this exception add it with the keyword WITH to one of the > + identifiers in the SPDX-Licenses tag: > + SPDX-License-Identifier: <SPDX-License> WITH Linux-syscall-note > + Exception-Text: > + Full exception text > + > + :: > + > + SPDX-Exception-Identifier: GCC-exception-2.0 > + SPDX-URL: https://spdx.org/licenses/GCC-exception-2.0.html > + SPDX-Licenses: GPL-2.0, GPL-2.0+ > + Usage-Guidance: > + The "GCC Runtime Library exception 2.0" is used together with one > + of the above SPDX-Licenses for code imported from the GCC runtime > + library. > + To use this exception add it with the keyword WITH to one of the > + identifiers in the SPDX-Licenses tag: > + SPDX-License-Identifier: <SPDX-License> WITH GCC-exception-2.0 > + Exception-Text: > + Full exception text > + > + > +All SPDX license identifiers and exceptions must have a corresponding file > +in the LICENSING subdirectories. This is required to allow tool > +verification (e.g. checkpatch.pl) and to have the licenses ready to read > +and extract right from the source, which is recommended by various FOSS > +organizations, e.g. the `FSFE REUSE initiative <https://reuse.software/>`_. Thanks, Mauro -- To unsubscribe from this list: send the line "unsubscribe linux-xfs" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Mauro, On Fri, 17 Nov 2017, Mauro Carvalho Chehab wrote: > Em Fri, 17 Nov 2017 11:00:33 +0100 (CET) > Thomas Gleixner <tglx@linutronix.de> escreveu: > > > Subject: Documentation: Add license-rules.rst to describe how to properly identify file licenses > > From: Thomas Gleixner <tglx@linutronix.de> > > Date: Fri, 10 Nov 2017 09:30:00 +0100 > > > > Add a file to the Documentation directory to describe how file licenses > > should be described in all kernel files, using the SPDX identifier, as well > > as where all licenses should be in the kernel source tree for people to > > refer to (LICENSES/). > > > > Thanks to Kate, Greg and Jonathan for review and editing and Jonas for the > > suggestions concerning the meta tags in the licenses files. > > > > Signed-off-by: Thomas Gleixner <tglx@linutronix.de> > > The document itself looks good, but I think it should also mention > what would be the expected values for the MODULE_LICENSE() macro and > how each license would be mapped into it. > > Right now, include/linux/module.h says: > > /* > * The following license idents are currently accepted as indicating free > * software modules > * > * "GPL" [GNU Public License v2 or later] > * "GPL v2" [GNU Public License v2] > * "GPL and additional rights" [GNU Public License v2 rights and more] > * "Dual BSD/GPL" [GNU Public License v2 > * or BSD license choice] > * "Dual MIT/GPL" [GNU Public License v2 > * or MIT license choice] > * "Dual MPL/GPL" [GNU Public License v2 > * or Mozilla license choice] > * > * The following other idents are available > * > * "Proprietary" [Non free products] > * > * There are dual licensed components, but when running with Linux it is the > * GPL that is relevant so this is a non issue. Similarly LGPL linked with GPL > * is a GPL combined work. > * > * This exists for several reasons > * 1. So modinfo can show license info for users wanting to vet their setup > * is free > * 2. So the community can ignore bug reports including proprietary modules > * 3. So vendors can do likewise based on their own policies > */ > #define MODULE_LICENSE(_license) MODULE_INFO(license, _license) > > In thesis, for every SPDX property at C or assembler files, we should have > a mapping into one of those MODULE_LICENSE(). I know. This is on the list of things which need to be addressed. The module license tags are a mess on their own and I have yet to come up with something smart to make this consistent. Whatever I came up with so far requires postprocessing. For files which have MODULE_LICENSE("...."): 1) Grab the SPDX identifier from the source file 2) Check whether the module license string is matching the SPDX license id. This is limited because the module license strings are pretty restricted. 2) Store the SPDX license id string in a separate module info variable Introcude a MODULE_LICENSE_SPDX macro which flags the module info storage as 'SPDXIFY' and let the postprocessor do: 1) Grab the SPDX identifier from the source file 2) Map it to the "known" module license string and store both in module info. That way tools can get access to the SPDX identifier and start to support it. I refrained from documenting anything in that area yet, because we really need to sit down and figure out a solution first. It's on that huge thingy which is append only, aka. todo list. Thanks, tglx -- To unsubscribe from this list: send the line "unsubscribe linux-xfs" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
On Fri, Nov 17, 2017 at 07:11:41PM +0100, Thomas Gleixner wrote: > Introcude a MODULE_LICENSE_SPDX macro which flags the module info storage > as 'SPDXIFY' and let the postprocessor do: Shouldn;t this be a FILE_LICENSE_SPDX? I'd also much prefer that over the nasty C99 comments to start with. And while I'm a bit behind on email I still haven't managed to find a good rationale for those to start with. So it would be good to figure this out before people start spamming the lists with all kinds of mass conversions and checkpatch fixes for licensing.. -- To unsubscribe from this list: send the line "unsubscribe linux-xfs" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Hi Thomas, > Add a file to the Documentation directory to describe how file licenses > should be described in all kernel files, using the SPDX identifier, as well > as where all licenses should be in the kernel source tree for people to > refer to (LICENSES/). I've given this a once over now, cross referenced against our recommendations and checked the patch set. Happy with the latest versions circulated (V4 of 1/11 and V3 of the others). Reviewed-by: Jonas Oberg <jonas@fsfe.org> Best,
On Fri, 17 Nov 2017, Christoph Hellwig wrote: > On Fri, Nov 17, 2017 at 07:11:41PM +0100, Thomas Gleixner wrote: > > Introcude a MODULE_LICENSE_SPDX macro which flags the module info storage > > as 'SPDXIFY' and let the postprocessor do: > > Shouldn;t this be a FILE_LICENSE_SPDX? I'd also much prefer that over > the nasty C99 comments to start with. And while I'm a bit behind on > email I still haven't managed to find a good rationale for those to > start with. > > So it would be good to figure this out before people start spamming > the lists with all kinds of mass conversions and checkpatch fixes > for licensing.. I tried solving this with a macro in the first place and ran into issues: - Does not work in headers, especially not in UAPI ones - Breaks in assembly, boot and other special source files. There was no easy solution to that and the result would have been to have macros in some files and not in others. So the fallback was to use a comment and Linus decided the '//' style. Thanks, tglx -- To unsubscribe from this list: send the line "unsubscribe linux-xfs" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Em Wed, 22 Nov 2017 12:12:04 +0100 (CET) Thomas Gleixner <tglx@linutronix.de> escreveu: > On Fri, 17 Nov 2017, Christoph Hellwig wrote: > > On Fri, Nov 17, 2017 at 07:11:41PM +0100, Thomas Gleixner wrote: > > > Introcude a MODULE_LICENSE_SPDX macro which flags the module info storage > > > as 'SPDXIFY' and let the postprocessor do: > > > > Shouldn;t this be a FILE_LICENSE_SPDX? I'd also much prefer that over > > the nasty C99 comments to start with. And while I'm a bit behind on > > email I still haven't managed to find a good rationale for those to > > start with. Yeah, I also find nasty to have things like this on each C file: // SPDX-License-Identifier: GPL-2.0 /* * Copyright ... * ... */ Also, one may forget that headers use /**/ and end by doing the wrong thing, as a common practice is to just cut-and-paste the same copyright header on both C and H files at development time. > > > > So it would be good to figure this out before people start spamming > > the lists with all kinds of mass conversions and checkpatch fixes > > for licensing.. > > I tried solving this with a macro in the first place and ran into issues: > > - Does not work in headers, especially not in UAPI ones Make headers_install could replace such macros by SPDX comments when installing on userspace. > - Breaks in assembly, boot and other special source files. There was no > easy solution to that and the result would have been to have macros in > some files and not in others. At the end, we have different markups, depending on the file type. I guess the main problem of using a macro is that a module composed by multiple C files will end by defining it multiple times. Not sure if gcc would do the right thing on grouping everything altogether and producing the right equivalent to MODULE_LICENSE(). Also, at least on media, I found cases where the same module has multiple licenses, e. g. some files that are grouped together on a module are GPL v2 only, while others are GPL v2+. > So the fallback was to use a comment and Linus decided the '//' style. > > Thanks, > > tglx > Thanks, Mauro -- To unsubscribe from this list: send the line "unsubscribe linux-xfs" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
On Wed, Nov 22, 2017 at 09:51:17AM -0200, Mauro Carvalho Chehab wrote: > Also, one may forget that headers use /**/ and end by doing the wrong > thing, as a common practice is to just cut-and-paste the same copyright > header on both C and H files at development time. Yes. > Make headers_install could replace such macros by SPDX comments when > installing on userspace. Agreed. Or for that matter we could simply stick to the comment version for UAPI headers only, and have a macro for everything else. > > - Breaks in assembly, boot and other special source files. There was no > > easy solution to that and the result would have been to have macros in > > some files and not in others. > > At the end, we have different markups, depending on the file type. > I guess the main problem of using a macro is that a module composed > by multiple C files will end by defining it multiple times. Not sure > if gcc would do the right thing on grouping everything altogether > and producing the right equivalent to MODULE_LICENSE(). We'd basically need to add a new entry to a section, similar to how say __setup works in the core kernel. But I think the important bit is to start with a macro now, even if it has zero functionality to start with - at least that enables us to fill the functionality once needed. > Also, at least on media, I found cases where the same module > has multiple licenses, e. g. some files that are grouped together on > a module are GPL v2 only, while others are GPL v2+. A module always has the least permissive license of all files. -- To unsubscribe from this list: send the line "unsubscribe linux-xfs" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Em Wed, 22 Nov 2017 14:23:29 +0100 Christoph Hellwig <hch@lst.de> escreveu: > On Wed, Nov 22, 2017 at 09:51:17AM -0200, Mauro Carvalho Chehab wrote: > > Also, one may forget that headers use /**/ and end by doing the wrong > > thing, as a common practice is to just cut-and-paste the same copyright > > header on both C and H files at development time. > > Yes. > > > Make headers_install could replace such macros by SPDX comments when > > installing on userspace. > > Agreed. Or for that matter we could simply stick to the comment version > for UAPI headers only, and have a macro for everything else. > > > > - Breaks in assembly, boot and other special source files. There was no > > > easy solution to that and the result would have been to have macros in > > > some files and not in others. > > > > At the end, we have different markups, depending on the file type. > > I guess the main problem of using a macro is that a module composed > > by multiple C files will end by defining it multiple times. Not sure > > if gcc would do the right thing on grouping everything altogether > > and producing the right equivalent to MODULE_LICENSE(). > > We'd basically need to add a new entry to a section, similar to how > say __setup works in the core kernel. But I think the important bit > is to start with a macro now, even if it has zero functionality to > start with - at least that enables us to fill the functionality once > needed. > > > Also, at least on media, I found cases where the same module > > has multiple licenses, e. g. some files that are grouped together on > > a module are GPL v2 only, while others are GPL v2+. > > A module always has the least permissive license of all files. Yes, but I'm not sure how a macro would work. I mean, if a driver foo has, let's say: foo-core.h: FILE_LICENSE_SPDX("SPDX-License-Identifier: GPL-2.0"); foo-core.c: FILE_LICENSE_SPDX("SPDX-License-Identifier: GPL-2.0"); foo-driver.c: FILE_LICENSE_SPDX("SPDX-License-Identifier: GPL-2.0+"); I can't see how to write such macro in a way that it would be discovering the license interception. Thanks, Mauro -- To unsubscribe from this list: send the line "unsubscribe linux-xfs" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
On Wed, Nov 22, 2017 at 09:51:17AM -0200, Mauro Carvalho Chehab wrote: > Em Wed, 22 Nov 2017 12:12:04 +0100 (CET) > Thomas Gleixner <tglx@linutronix.de> escreveu: > > > On Fri, 17 Nov 2017, Christoph Hellwig wrote: > > > On Fri, Nov 17, 2017 at 07:11:41PM +0100, Thomas Gleixner wrote: > > > > Introcude a MODULE_LICENSE_SPDX macro which flags the module info storage > > > > as 'SPDXIFY' and let the postprocessor do: > > > > > > Shouldn;t this be a FILE_LICENSE_SPDX? I'd also much prefer that over > > > the nasty C99 comments to start with. And while I'm a bit behind on > > > email I still haven't managed to find a good rationale for those to > > > start with. > > Yeah, I also find nasty to have things like this on each C file: > > // SPDX-License-Identifier: GPL-2.0 > /* > * Copyright ... > * ... > */ > > Also, one may forget that headers use /**/ and end by doing the wrong > thing, as a common practice is to just cut-and-paste the same copyright > header on both C and H files at development time. You break the build when you get it wrong, so you will notice it. For most "internal" .h files, using // is just fine. Yes, it's "ugly", but again, that's what Linus said he wanted it to look like, take it up with him :) > > > So it would be good to figure this out before people start spamming > > > the lists with all kinds of mass conversions and checkpatch fixes > > > for licensing.. > > > > I tried solving this with a macro in the first place and ran into issues: > > > > - Does not work in headers, especially not in UAPI ones > > Make headers_install could replace such macros by SPDX comments when > installing on userspace. The big issue is when you build, putting those macros all into something logical is a mess. I too tried it and failed. But feel to give it a go if you think it is possible :) thanks, greg k-h -- To unsubscribe from this list: send the line "unsubscribe linux-xfs" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
On Fri 2017-11-17 15:06:39, Mauro Carvalho Chehab wrote: > Hi Thomas, > > Em Fri, 17 Nov 2017 11:00:33 +0100 (CET) > Thomas Gleixner <tglx@linutronix.de> escreveu: > > > Subject: Documentation: Add license-rules.rst to describe how to properly identify file licenses > > From: Thomas Gleixner <tglx@linutronix.de> > > Date: Fri, 10 Nov 2017 09:30:00 +0100 > > > > Add a file to the Documentation directory to describe how file licenses > > should be described in all kernel files, using the SPDX identifier, as well > > as where all licenses should be in the kernel source tree for people to > > refer to (LICENSES/). > > > > Thanks to Kate, Greg and Jonathan for review and editing and Jonas for the > > suggestions concerning the meta tags in the licenses files. > > > > Signed-off-by: Thomas Gleixner <tglx@linutronix.de> > > The document itself looks good, but I think it should also mention > what would be the expected values for the MODULE_LICENSE() macro and > how each license would be mapped into it. > > Right now, include/linux/module.h says: > > /* > * The following license idents are currently accepted as indicating free > * software modules > * > * "GPL" [GNU Public License v2 or later] Hmm. AFAICT Greg translated GPL as GPL v1 or later. That seemed wrong... and now it seems even more wrong. Pavel
On Wed 2017-11-22 14:48:04, Greg Kroah-Hartman wrote: > On Wed, Nov 22, 2017 at 09:51:17AM -0200, Mauro Carvalho Chehab wrote: > > Em Wed, 22 Nov 2017 12:12:04 +0100 (CET) > > Thomas Gleixner <tglx@linutronix.de> escreveu: > > > > > On Fri, 17 Nov 2017, Christoph Hellwig wrote: > > > > On Fri, Nov 17, 2017 at 07:11:41PM +0100, Thomas Gleixner wrote: > > > > > Introcude a MODULE_LICENSE_SPDX macro which flags the module info storage > > > > > as 'SPDXIFY' and let the postprocessor do: > > > > > > > > Shouldn;t this be a FILE_LICENSE_SPDX? I'd also much prefer that over > > > > the nasty C99 comments to start with. And while I'm a bit behind on > > > > email I still haven't managed to find a good rationale for those to > > > > start with. > > > > Yeah, I also find nasty to have things like this on each C file: > > > > // SPDX-License-Identifier: GPL-2.0 > > /* > > * Copyright ... > > * ... > > */ > > > > Also, one may forget that headers use /**/ and end by doing the wrong > > thing, as a common practice is to just cut-and-paste the same copyright > > header on both C and H files at development time. > > You break the build when you get it wrong, so you will notice it. For > most "internal" .h files, using // is just fine. > > Yes, it's "ugly", but again, that's what Linus said he wanted it to look > like, take it up with him :) Linus said: # So in general, the _hope_ is that we can just end up replacing # existing boilerplate comments with that single line SPDX comment # (using "//" in *.[ch] files, but obviously some other kinds of files # end up having a different comment character, typically '#'). That does not sound like he was deciding between /* */ and //. And actually this was in context of files with no existing license. You made the ugly patches. Stop hiding behind Linus. Pavel
On Sat, Nov 25, 2017 at 9:04 AM, Pavel Machek <pavel@ucw.cz> wrote: > > That does not sound like he was deciding between /* */ and //. And > actually this was in context of files with no existing license. You > made the ugly patches. Stop hiding behind Linus. No, Linus happily stands up for //. I really don't like one-liner /* */ comments. Let's face it, // was the _one_ thing C++ got right, among all the horrible bad decisions. I think we should just start moving to // in general, but only when adding new ones (ie I don't want to see any automatic conversion patches). And it's _particularly_ true for the whole case where we mix one-liners like the SPDX line with block comments. That's where /* */ really sucks. Linus -- To unsubscribe from this list: send the line "unsubscribe linux-xfs" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
On Sat 2017-11-25 09:11:58, Linus Torvalds wrote: > On Sat, Nov 25, 2017 at 9:04 AM, Pavel Machek <pavel@ucw.cz> wrote: > > > > That does not sound like he was deciding between /* */ and //. And > > actually this was in context of files with no existing license. You > > made the ugly patches. Stop hiding behind Linus. > > No, Linus happily stands up for //. > > I really don't like one-liner /* */ comments. Let's face it, // was > the _one_ thing C++ got right, among all the horrible bad decisions. > > I think we should just start moving to // in general, but only when > adding new ones (ie I don't want to see any automatic conversion > patches). > > And it's _particularly_ true for the whole case where we mix > one-liners like the SPDX line with block comments. That's where /* */ > really sucks. I agree that we should not do /* SPDX-License-Identifier: GPL-2.0+ */ /* * Driver for SMSC USB3503 USB 2.0 hub controller driver * * Copyright (c) 2012-2013 Dongjin Kim (tobetter@gmail.com) */ There's logical place in the comment, and it should look like this: /* * Driver for SMSC USB3503 USB 2.0 hub controller driver * * SPDX-License-Identifier: GPL-2.0+ * Copyright (c) 2012-2013 Dongjin Kim (tobetter@gmail.com) */ So I'm not saying "use one-line comments with SPDX identifier". I'm saying place it where people expect it. Best regards, Pavel
On Sat, Nov 25, 2017 at 9:17 AM, Pavel Machek <pavel@ucw.cz> wrote: > > There's logical place in the comment, and it should look like this: > > /* > * Driver for SMSC USB3503 USB 2.0 hub controller driver > * > * SPDX-License-Identifier: GPL-2.0+ > * Copyright (c) 2012-2013 Dongjin Kim (tobetter@gmail.com) > */ And this is *exactly* what I don't want o see, because now the SPDX placement is basically entirely random, and we'll get stupid conflicts that are must nastier, and people will get it wrong and we'll end up with two lines etc etc headaches. Yes, the single line at the top _also_ causes conflicts, but they are really easy to resolve exactly because there is absolutely no ambiguity about what the resolution is, and there is no question that there could be two different SPDX lines in the file. The "//" format is ambiguous and simple, and works well for the first line. And if we have the long-term plan to move over to // (which I really hope for), it's also the cleanest of them all. Btw, your exact line is also an example of another thing I *never* want to see: indentation of the identifier. I'm not sure what was going on there, and what you tried to line up, but it has already happened once in include/dt-bindings/clock/boston-clock.h, and I suspect it was *exactly* because it was in a /* block comment and people tried to make it match that comment. THAT IS WRONG. We already had the damn "random whitespace fixes" crap with the existing license mess. Let's learn from our mistakes, AND NOT DO IT AGAIN! So I want the format to be _fixed_. On the very first line that the file format allows, with no whitespace garbage, and no "let's try to make it pretty and match the rest". Seriously. You should be able to do git grep -h SPDX-License-Identifier: | sort | uniq -c and not get fifty different versions just because of stupid "let's match things around it" crap. If you want to match something, switch to using '//' at he top copyright comment, and remove the garbage boilerplate. Linus -- To unsubscribe from this list: send the line "unsubscribe linux-xfs" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Em Sat, 25 Nov 2017 09:30:46 -1000 Linus Torvalds <torvalds@linux-foundation.org> escreveu: > On Sat, Nov 25, 2017 at 9:17 AM, Pavel Machek <pavel@ucw.cz> wrote: > > > > There's logical place in the comment, and it should look like this: > > > > /* > > * Driver for SMSC USB3503 USB 2.0 hub controller driver > > * > > * SPDX-License-Identifier: GPL-2.0+ > > * Copyright (c) 2012-2013 Dongjin Kim (tobetter@gmail.com) > > */ > > And this is *exactly* what I don't want o see, because now the SPDX > placement is basically entirely random, and we'll get stupid conflicts > that are must nastier, and people will get it wrong and we'll end up > with two lines etc etc headaches. > > Yes, the single line at the top _also_ causes conflicts, but they are > really easy to resolve exactly because there is absolutely no > ambiguity about what the resolution is, and there is no question that > there could be two different SPDX lines in the file. > > The "//" format is ambiguous and simple, and works well for the first line. > > And if we have the long-term plan to move over to // (which I really > hope for), it's also the cleanest of them all. Let me see if I got it straight. At drivers/media/common/siano/smsir.c, we have, currently: /**************************************************************** Siano Mobile Silicon, Inc. MDTV receiver kernel modules. Copyright (C) 2006-2009, Uri Shkolnik Copyright (c) 2010 - Mauro Carvalho Chehab - Ported the driver to use rc-core - IR raw event decoding is now done at rc-core - Code almost re-written This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>. ****************************************************************/ With is completely out of standard. I'd like to add an SPDX tag there and, while doing that, adjust the comments. So, if I understand well, your preference would be to make it like: // SPDX-License-Identifier: GPL-2.0+ // // Siano Mobile Silicon, Inc. // MDTV receiver kernel modules. // Copyright (C) 2006-2009, Uri Shkolnik // // Copyright (c) 2010 - Mauro Carvalho Chehab // - Ported the driver to use rc-core // - IR raw event decoding is now done at rc-core // - Code almost re-written Right? Also, what about the header file (that, currently, has an identical header? The way it was proposed (with /**/), it would be: /* SPDX-License-Identifier: GPL-2.0+ */ /* * Siano Mobile Silicon, Inc. * MDTV receiver kernel modules. * Copyright (C) 2006-2009, Uri Shkolnik * * Copyright (c) 2010 - Mauro Carvalho Chehab * - Ported the driver to use rc-core * - IR raw event decoding is now done at rc-core * - Code almost re-written */ With, IMHO, looks really ugly. Thanks, Mauro -- To unsubscribe from this list: send the line "unsubscribe linux-xfs" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
On Sat, Nov 25, 2017 at 9:53 AM, Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote: > > Let me see if I got it straight. At drivers/media/common/siano/smsir.c, > we have, currently: .. snip snip .. > With is completely out of standard. I'd like to add an SPDX tag there > and, while doing that, adjust the comments. > > So, if I understand well, your preference would be to make it like: > > // SPDX-License-Identifier: GPL-2.0+ > // > // Siano Mobile Silicon, Inc. > // MDTV receiver kernel modules. > // Copyright (C) 2006-2009, Uri Shkolnik > // > // Copyright (c) 2010 - Mauro Carvalho Chehab > // - Ported the driver to use rc-core > // - IR raw event decoding is now done at rc-core > // - Code almost re-written > > Right? Exactly. I would also like to make clear that this is not a "let's do this in bulk and automatically". But let's just say that if the "//" for the SPDX line ends up encouraging people towards this kind of format over the long run, I think that would be lovely. The /* */ format really ends up encouraging some odd formatting. Your example with the whole "box of stars" is not standard kernel format, but it's surprisingly common. And you find various lopsided versions of the multi-line thing, and even when you do *single* lines, the /* */ thing ends up being something where people try to align the closing "*/" part. Honestly now, how many people have seen things like struct somestruct { int member; /* For Xyz */ int other; /* For Abracadabra */ ... where people try to align that ending thing? Or tell me you haven't seen block comments where people do /* This is a multi-line * thing that tries to be dense */ and other odd formats that are just ugly and unbalanced. That's why I think "//" ends up being better in the end. And yes, I've changed my mind over time. Had you asked me ten or fifteen years ago, I probably would have said that "//" is not real C. Linus -- To unsubscribe from this list: send the line "unsubscribe linux-xfs" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Pavel: On Sat, Nov 25, 2017 at 7:51 PM, Pavel Machek <pavel@ucw.cz> wrote: > On Fri 2017-11-17 15:06:39, Mauro Carvalho Chehab wrote: >> Hi Thomas, >> >> Em Fri, 17 Nov 2017 11:00:33 +0100 (CET) >> Thomas Gleixner <tglx@linutronix.de> escreveu: >> >> > Subject: Documentation: Add license-rules.rst to describe how to properly identify file licenses >> > From: Thomas Gleixner <tglx@linutronix.de> >> > Date: Fri, 10 Nov 2017 09:30:00 +0100 >> > >> > Add a file to the Documentation directory to describe how file licenses >> > should be described in all kernel files, using the SPDX identifier, as well >> > as where all licenses should be in the kernel source tree for people to >> > refer to (LICENSES/). >> > >> > Thanks to Kate, Greg and Jonathan for review and editing and Jonas for the >> > suggestions concerning the meta tags in the licenses files. >> > >> > Signed-off-by: Thomas Gleixner <tglx@linutronix.de> >> >> The document itself looks good, but I think it should also mention >> what would be the expected values for the MODULE_LICENSE() macro and >> how each license would be mapped into it. >> >> Right now, include/linux/module.h says: >> >> /* >> * The following license idents are currently accepted as indicating free >> * software modules >> * >> * "GPL" [GNU Public License v2 or later] > > Hmm. AFAICT Greg translated GPL as GPL v1 or later. That seemed > wrong... and now it seems even more wrong. While this may come out as weird or wrong, this is neither wrong nor "more wrong" when you dive in the details: 1. the meaning of a bare "GPL" in MODULE_LICENSE is well defined in module.h as "GPL 2.0 or later" so there is no ambiguity there. It would have been best to align this with SPDX, but this would break instantly so many out of tree kernel modules and module loading tools that expect these hard coded values and conventions that it is not worth changing it IMHO. 2. the meaning of a bare "GPL" as a the only license notice is also well defined in the GPL 2.0 text itself in section 9 [1] and means any version of the GPL that therefore can be made clear as GPL-1.0 or later, i.e. GPL-1.+: " If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation. " Therefore I do not think Greg did any translation and got anything wrong but used exactly the convention in 2. For instance when the only license notice in a file was a terse and unclear: "Copyright (c) Jane Doe, GPL" or "Copyright (c) John Doe, GPL'ed" then the resulting SPDX license id applied was "GPL-1.0+" I personally think this is unfortunate that we have warts like this: it could have been the intent of author, or an oversight, or the author may have meant 2.0.... we can only guess! What is clear is that in these cases and short of any other indication, "GPL-1.0+" is the precise meaning that "GPL" or "GPL'ed" has in a notice outside of the MODULE_LICENSE macro. Note that no MODULE_LICENSE macro was harmed in the process.... though having SPDX ids makes quite visible some discrepancies as you noticed such as when: - a MODULE_LICENSE is "GPL" and the top level license is "GPL 2.0 only": here the MODULE_LICENSE would need to be fixed to "GPL v2" - or MODULE_LICENSE is "GPL v2" and the top level license is "GPL 2.0 or later": here the MODULE_LICENSE would need to be fixed to "GPL" These will need to be fixed over time and this is made easier with the clarity brought by the SPDX id. My take there is that the best approach is likely: 1. the top level license notice should take precedence over the MODULE_LICENSE and MODULE_LICENSE should be updated accordingly 2. you might want an ack or a review from the original author in these weird cases of mismatch [1] https://www.gnu.org/licenses/old-licenses/gpl-2.0.html#section9
On Fri, 2017-11-17 at 11:00 +0100, Thomas Gleixner wrote:
> spdx
Is there something preventing this from being applied
to some tree included in -next?
--
To unsubscribe from this list: send the line "unsubscribe linux-xfs" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
On Thu, 14 Dec 2017, Joe Perches wrote: > On Fri, 2017-11-17 at 11:00 +0100, Thomas Gleixner wrote: > > spdx > > Is there something preventing this from being applied > to some tree included in -next? Nothing than me being busy and not coming around to fix the last review comments. -- To unsubscribe from this list: send the line "unsubscribe linux-xfs" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Hi, I'm definitively late to the party but... On 17/11/2017 at 11:00:33 +0100, Thomas Gleixner wrote: > +2. Style: > + > + The SPDX license identifier is added in form of a comment. The comment > + style depends on the file type:: > + > + C source: // SPDX-License-Identifier: <SPDX License Expression> > + C header: /* SPDX-License-Identifier: <SPDX License Expression> */ > + ASM: /* SPDX-License-Identifier: <SPDX License Expression> */ > + scripts: # SPDX-License-Identifier: <SPDX License Expression> > + .rst: .. SPDX-License-Identifier: <SPDX License Expression> > + .dts{i}: // SPDX-License-Identifier: <SPDX License Expression> dtc doesn't handle // comments. This works in the kernel tree because dts files are preprocessed by CPP. But this doesn't work when using dtc directly (most likely when compiling DT overlays). So, the choice is between making dtc handle // comments or changing the documentation. I don't have an opinion and Rob doesn't seem to care but I think we need to do something now instead of letting each maintainer have to handle this issue. > + If a specific tool cannot handle the standard comment style, then the > + appropriate comment mechanism which the tool accepts shall be used. This > + is the reason for having the "/\* \*/" style comment in C header > + files. There was build breakage observed with generated .lds files where > + 'ld' failed to parse the C++ comment. This has been fixed by now, but > + there are still older assembler tools which cannot handle C++ style > + comments. > +
On Fri, Jan 05, 2018 at 02:05:26PM +0100, Alexandre Belloni wrote: > Hi, > > I'm definitively late to the party but... > > On 17/11/2017 at 11:00:33 +0100, Thomas Gleixner wrote: > > +2. Style: > > + > > + The SPDX license identifier is added in form of a comment. The comment > > + style depends on the file type:: > > + > > + C source: // SPDX-License-Identifier: <SPDX License Expression> > > + C header: /* SPDX-License-Identifier: <SPDX License Expression> */ > > + ASM: /* SPDX-License-Identifier: <SPDX License Expression> */ > > + scripts: # SPDX-License-Identifier: <SPDX License Expression> > > + .rst: .. SPDX-License-Identifier: <SPDX License Expression> > > + .dts{i}: // SPDX-License-Identifier: <SPDX License Expression> > > dtc doesn't handle // comments. This works in the kernel tree because > dts files are preprocessed by CPP. But this doesn't work when using dtc > directly (most likely when compiling DT overlays). So, the choice is > between making dtc handle // comments or changing the documentation. Does all the CPP macros that we use for things like GPIOs work when you avoid CPP? What I'm saying is that preprocessing the DTS in the kernel tree with CPP appears to be a necessity, and doing so will deal with the C++ comments.
On 01/05/18 05:05, Alexandre Belloni wrote: > Hi, > > I'm definitively late to the party but... > > On 17/11/2017 at 11:00:33 +0100, Thomas Gleixner wrote: >> +2. Style: >> + >> + The SPDX license identifier is added in form of a comment. The comment >> + style depends on the file type:: >> + >> + C source: // SPDX-License-Identifier: <SPDX License Expression> >> + C header: /* SPDX-License-Identifier: <SPDX License Expression> */ >> + ASM: /* SPDX-License-Identifier: <SPDX License Expression> */ >> + scripts: # SPDX-License-Identifier: <SPDX License Expression> >> + .rst: .. SPDX-License-Identifier: <SPDX License Expression> >> + .dts{i}: // SPDX-License-Identifier: <SPDX License Expression> > > dtc doesn't handle // comments. This works in the kernel tree because dtc does handle // comments. $ cat test_comment.dts /dts-v1/; // this is comment 1 /* this is comment 2 */ / { #address-cells = < 1 >; #size-cells = < 1 >; // this is comment 3 tree_1: soc@0 { reg = <0x0 0x0>; }; }; Using the dtc version in linux v4.14: $ dtc -v Version: DTC 1.4.4-g756ffc4f $ dtc -O dts test_comment.dts /dts-v1/; / { #address-cells = <0x1>; #size-cells = <0x1>; tree_1: soc@0 { reg = <0x0 0x0>; }; }; Using the latest dtc version in the git_dtc repo: $ dtc -v Version: DTC 1.4.6-ge5438801 $ dtc -O dts test_comment.dts /dts-v1/; / { #address-cells = <0x1>; #size-cells = <0x1>; tree_1: soc@0 { reg = <0x0 0x0>; }; }; -Frank > dts files are preprocessed by CPP. But this doesn't work when using dtc > directly (most likely when compiling DT overlays). So, the choice is > between making dtc handle // comments or changing the documentation. > > I don't have an opinion and Rob doesn't seem to care but I think we need > to do something now instead of letting each maintainer have to handle > this issue. > >> + If a specific tool cannot handle the standard comment style, then the >> + appropriate comment mechanism which the tool accepts shall be used. This >> + is the reason for having the "/\* \*/" style comment in C header >> + files. There was build breakage observed with generated .lds files where >> + 'ld' failed to parse the C++ comment. This has been fixed by now, but >> + there are still older assembler tools which cannot handle C++ style >> + comments. >> + -- To unsubscribe from this list: send the line "unsubscribe linux-xfs" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
On 05/01/2018 at 14:48:04 -0800, Frank Rowand wrote: > On 01/05/18 05:05, Alexandre Belloni wrote: > > Hi, > > > > I'm definitively late to the party but... > > > > On 17/11/2017 at 11:00:33 +0100, Thomas Gleixner wrote: > >> +2. Style: > >> + > >> + The SPDX license identifier is added in form of a comment. The comment > >> + style depends on the file type:: > >> + > >> + C source: // SPDX-License-Identifier: <SPDX License Expression> > >> + C header: /* SPDX-License-Identifier: <SPDX License Expression> */ > >> + ASM: /* SPDX-License-Identifier: <SPDX License Expression> */ > >> + scripts: # SPDX-License-Identifier: <SPDX License Expression> > >> + .rst: .. SPDX-License-Identifier: <SPDX License Expression> > >> + .dts{i}: // SPDX-License-Identifier: <SPDX License Expression> > > > > dtc doesn't handle // comments. This works in the kernel tree because > > dtc does handle // comments. > Hum, correct. I got a report saying it didn't and when I only checked the COMMENT line of dtc-lexer.l. For whatever reason, I missed the following line handling c++ comments. I'll get back to the original report, trying to find why it was not compiling.
--- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -13,6 +13,18 @@ documents into a coherent whole. Please documentation are welcome; join the linux-doc list at vger.kernel.org if you want to help out. +Licensing documentation +----------------------- + +The following describes the license of the Linux kernel source code +(GPLv2), how to properly mark the license of individual files in the source +tree, as well as links to the full license text. + +.. toctree:: + :maxdepth: 2 + + process/license-rules.rst + User-oriented documentation --------------------------- --- /dev/null +++ b/Documentation/process/license-rules.rst @@ -0,0 +1,370 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Linux kernel licensing rules +============================ + +The Linux Kernel is provided under the terms of the GNU General Public +License version 2 only (GPL-2.0), as published by the Free Software +Foundation, and provided in the COPYING file. This documentation file is +not meant to replace the COPYING file, but provides a description of how +each source file should be annotated to make the licensing it is governed +under clear and unambiguous. + +The license in the COPYING file applies to the kernel source as a whole, +though individual source files can have a different license which is +required to be compatible with the GPL-2.0:: + + GPL-1.0+ : GNU General Public License v1.0 or later + GPL-2.0+ : GNU General Public License v2.0 or later + LGPL-2.0 : GNU Library General Public License v2 only + LGPL-2.0+ : GNU Library General Public License v2 or later + LGPL-2.1 : GNU Lesser General Public License v2.1 only + LGPL-2.1+ : GNU Lesser General Public License v2.1 or later + +Aside from that, individual files can be provided under a dual license, +e.g. one of the compatible GPL variants and alternatively under a +permissive license like BSD, MIT etc. + +The User-space API (UAPI) header files, which describe the interface of +user-space programs to the kernel are a special case. According to the +note in the kernel COPYING file, the syscall interface is a clear boundary, +which does not extend the GPL requirements to any software which uses it to +communicate with the kernel. Because the UAPI headers must be includable +into any source files which create an executable running on the Linux +kernel, the exception must be documented by a special license expression. + +The common way of expressing the license of a source file is to add the +matching boiler plate text into the top comment of the file. Due to +formatting, typos etc. these "boiler plates" are hard to validate for +tools which are used in the context of license compliance. + +An alternative to boilerplate text is the use of Software Package Data +Exchange (SPDX) license identifiers in each source file. SPDX license +identifiers are machine parsable and precise shorthands for the license +under which the content of the file is contributed. SPDX license +identifiers are managed by the SPDX Workgroup at the Linux Foundation and +have been agreed on by partners throughout the industry, tool vendors, and +legal teams. For further information see https://spdx.org/ + +The Linux kernel requires the precise SPDX identifier in all source files. +The valid identifiers used in the kernel are explained in the section +`License identifiers`_ and have been retrieved from the official SPDX +license list at https://spdx.org/licenses/ along with the license texts. + +License identifier syntax +------------------------- + +1. Placement: + + The SPDX license identifier in kernel files shall be added at the first + possible line in a file which can contain a comment. For the majority + or files this is the first line, except for scripts which require the + '#!PATH_TO_INTERPRETER' in the first line. For those scripts the SPDX + identifier goes into the second line. + +| + +2. Style: + + The SPDX license identifier is added in form of a comment. The comment + style depends on the file type:: + + C source: // SPDX-License-Identifier: <SPDX License Expression> + C header: /* SPDX-License-Identifier: <SPDX License Expression> */ + ASM: /* SPDX-License-Identifier: <SPDX License Expression> */ + scripts: # SPDX-License-Identifier: <SPDX License Expression> + .rst: .. SPDX-License-Identifier: <SPDX License Expression> + .dts{i}: // SPDX-License-Identifier: <SPDX License Expression> + + If a specific tool cannot handle the standard comment style, then the + appropriate comment mechanism which the tool accepts shall be used. This + is the reason for having the "/\* \*/" style comment in C header + files. There was build breakage observed with generated .lds files where + 'ld' failed to parse the C++ comment. This has been fixed by now, but + there are still older assembler tools which cannot handle C++ style + comments. + +| + +3. Syntax: + + A <SPDX License Expression> is either an SPDX short form license + identifier found on the SPDX License List, or when multiple licenses + apply, an expression consisting of keywords "AND", "OR", and "WITH" + separating SPDX short form license identifiers surrounded by "(", ")". + + License identifiers for licenses like [L]GPL with the 'or later' option + are constructed by using a "+" for indicating the 'or later' option.:: + + // SPDX-License-Identifier: GPL-2.0+ + // SPDX-License-Identifier: LGPL-2.1+ + + WITH should be used when there is a modifier to a license needed. + For example, the linux kernel UAPI files use the expression:: + + // SPDX-License-Identifier: (GPL-2.0 WITH Linux-syscall-note) + // SPDX-License-Identifier: (GPL-2.0+ WITH Linux-syscall-note) + + Other examples using WITH exceptions found in the kernel are:: + + // SPDX-License-Identifier: (GPL-2.0 WITH mif-exception) + // SPDX-License-Identifier: (GPL-2.0+ WITH GCC-exception-2.0) + + Exceptions can only be used with particular License identifiers. The + valid License identifiers are listed in the tags of the exception text + file. For details see the point `Exceptions`_ in the chapter `License + identifiers`_. + + OR should be used if the file is dual licensed and only one license is + to be selected. For example, some dtsi files are available under dual + licenses:: + + // SPDX-License-Identifier: (GPL-2.0 OR BSD-3-Clause) + + Examples from the kernel for license expressions in dual licensed files:: + + // SPDX-License-Identifier: (GPL-2.0 OR MIT) + // SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) + // SPDX-License-Identifier: (GPL-2.0 OR Apache-2.0) + // SPDX-License-Identifier: (GPL-2.0 OR MPL-1.1) + // SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR MIT) + // SPDX-License-Identifier: ((GPL-1.0+ OR BSD-3-Clause) OR OpenSSL) + + AND should be used if the file has multiple licenses whose terms all + apply to use the file. For example, if code is inherited from another + project and permission has been given to put it in the kernel, but the + original license terms need to remain in effect:: + + // SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) AND MIT) + + Another other example where both sets of license terms need to be + adhered to is:: + + // SPDX-License-Identifier: (GPL-1.0+ AND LGPL-2.1+) + +License identifiers +------------------- + +The licenses currently used, as well as the licenses for code added to the +kernel, can be broken down into: + +1. _`Preferred licenses`: + + Whenever possible these licenses should be used as they are known to be + fully compatible and widely used. These licenses are available from the + directory:: + + LICENSES/preferred/ + + in the kernel source tree. + + The files in this directory the full license text and `Metatags`_. + + The file names are identical to the SPDX license identifier which shall + be used for the license in source files. + + Examples:: + + LICENSES/preferred/GPL-2.0 + + Contains the GPL version 2 license text and the required metatags:: + + LICENSES/preferred/MIT + + Contains the MIT license text and the required metatags + + _`Metatags`: + + The following meta tags must be available in a license file: + + - Valid-License-Identifier: + + One or more lines which declare which License Identifiers are valid + inside the project to reference this particular license text. Usually + this is a single valid identifier, but e.g. for licenses with the 'or + later' options two identifiers are valid. + + - SPDX-URL: + + The URL of the SPDX page which contains additional information related + to the license. + + - Usage-Guidance: + + Freeform text for usage advice. The text must include correct examples + for the SPDX license identifiers as they should be put into source + files according to the `License identifier syntax`_ guidelines. + + - License-Text: + + All text after this tag is treated as the original license text + + File format examples:: + + Valid-License-Identifier: GPL-2.0 + Valid-License-Identifier: GPL-2.0+ + SPDX-URL: https://spdx.org/licenses/GPL-2.0.html + Usage-Guide: + To use this license in source code, put one of the following SPDX + tag/value pairs into a comment according to the placement + guidelines in the licensing rules documentation. + For 'GNU General Public License (GPL) version 2 only' use: + SPDX-License-Identifier: GPL-2.0 + For 'GNU General Public License (GPL) version 2 or any later version' use: + SPDX-License-Identifier: GPL-2.0+ + License-Text: + Full license text + + :: + + SPDX-License-Identifier: MIT + SPDX-URL: https://spdx.org/licenses/MIT.html + Usage-Guide: + To use this license in source code, put the following SPDX + tag/value pair into a comment according to the placement + guidelines in the licensing rules documentation. + SPDX-License-Identifier: MIT + License-Text: + Full license text + +| + +2. Not recommended licenses: + + These licenses should only be used for existing code or for importing + code from a different project. These licenses are available from the + directory:: + + LICENSES/other/ + + in the kernel source tree. + + The files in this directory the full license text and `Metatags`_. + + The file names are identical to the SPDX license identifier which shall be + used for the license in source files. + + Examples:: + + LICENSES/other/ISC + + Contains the Internet Systems Consortium license text and the required + metatags:: + + LICENSES/other/ZLib + + Contains the ZLIB license text and the required metatags. + + Metatags: + + The metatag requirements for 'other' licenses are identical to the + requirements of the `Preferred licenses`_. + + File format example:: + + Valid-License-Identifier: ISC + SPDX-URL: https://spdx.org/licenses/ISC.html + Usage-Guide: + Usage of this license in the kernel for new code is discouraged + and it should solely be used for importing code from an already + existing project. + To use this license in source code, put the following SPDX + tag/value pair into a comment according to the placement + guidelines in the licensing rules documentation. + SPDX-License-Identifier: ISC + License-Text: + Full license text + +| + +3. _`Exceptions`: + + Some licenses can be amended with exceptions which grant certain rights + which the original license does not. These exceptions are available + from the directory:: + + LICENSES/exceptions/ + + in the kernel source tree. The files in this directory contain the full + exception text and the required `Exception Metatags`_. + + Examples:: + + LICENSES/exceptions/Linux-syscall-note + + Contains the Linux syscall exception as documented in the COPYING + file of the Linux kernel, which is used for UAPI header files. + e.g. /\* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note \*/:: + + LICENSES/exceptions/GCC-exception-2.0 + + Contains the GCC 'linking exception' which allows to link any binary + independent of its license against the compiled version of a file marked + with this exception. This is required for creating runnable executables + from source code which is not compatible with the GPL. + + _`Exception Metatags`: + + The following meta tags must be available in an exception file: + + - SPDX-Exception-Identifier: + + One exception identifier which can be used with SPDX license + identifiers. + + - SPDX-URL: + + The URL of the SPDX page which contains additional information related + to the exception. + + - SPDX-Licenses: + + A comma separated list of SPDX license identifiers for which the + exception can be used. + + - Usage-Guidance: + + Freeform text for usage advice. The text must be followed by correct + examples for the SPDX license identifiers as they should be put into + source files according to the `License identifier syntax`_ guidelines. + + - Exception-Text: + + All text after this tag is treated as the original exception text + + File format examples:: + + SPDX-Exception-Identifier: Linux-syscall-note + SPDX-URL: https://spdx.org/licenses/Linux-syscall-note.html + SPDX-Licenses: GPL-2.0, GPL-2.0+, GPL-1.0+, LGPL-2.0, LGPL-2.0+, LGPL-2.1, LGPL-2.1+ + Usage-Guidance: + This exception is used together with one of the above SPDX-Licenses + to mark user-space API (uapi) header files so they can be included + into non GPL compliant user-space application code. + To use this exception add it with the keyword WITH to one of the + identifiers in the SPDX-Licenses tag: + SPDX-License-Identifier: <SPDX-License> WITH Linux-syscall-note + Exception-Text: + Full exception text + + :: + + SPDX-Exception-Identifier: GCC-exception-2.0 + SPDX-URL: https://spdx.org/licenses/GCC-exception-2.0.html + SPDX-Licenses: GPL-2.0, GPL-2.0+ + Usage-Guidance: + The "GCC Runtime Library exception 2.0" is used together with one + of the above SPDX-Licenses for code imported from the GCC runtime + library. + To use this exception add it with the keyword WITH to one of the + identifiers in the SPDX-Licenses tag: + SPDX-License-Identifier: <SPDX-License> WITH GCC-exception-2.0 + Exception-Text: + Full exception text + + +All SPDX license identifiers and exceptions must have a corresponding file +in the LICENSING subdirectories. This is required to allow tool +verification (e.g. checkpatch.pl) and to have the licenses ready to read +and extract right from the source, which is recommended by various FOSS +organizations, e.g. the `FSFE REUSE initiative <https://reuse.software/>`_.