mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-12-05 12:05:22 +00:00
.. | ||
test | ||
make-id-list | ||
README | ||
relic |
ReadMe for relic.py (a Mozilla relicensing tool) This script is intended to facilitate re-licensing the Mozilla source tree pursuant to <http://mozilla.org/MPL/>. It cannot do the full job automatically but handles most of the grunt work. Table of Contents: The Problem Getting Started Basic Usage What Files are Processed Error Handling (--force) Unfinished Business Contributors The Problem: The basic problem is that Mozilla has a lot of files. The goal is to have all the files (with a few minor exceptions) contain a leading license block that is either the MPL/GPL/LGPL tri-license or the NPL/GPL/LGPL tri-license. Because this was never rigorously enforced a lot of cleanup is necessary to correct license blocks in Mozilla's files. This script will traverse the given directory(s)/file(s) and fixup the leading license block, or give an error message explaining why it cannot. (It also has modes to just scan for and summarize license info.) Getting Started: While 'relic.py' is probably quite portable to Windows it has not been tested there. There may be some hidden path-delimiter bugs. It is probably best to just run this script on Linux. To use: - crack the relic-<version>.tar.gz tarball in some directory - call './relic.py --help' to learn the basic usage - play with './relic.py ...' as desired. Basic Usage: 'relic.py' has a --help option that explains the basic usage but I'll go through some examples here. In our examples we will work on re-licensing the mozilla/js/src directory tree. 'relic.py' has three modes. (1) List license info on each file processed (the default) $ ./relic.py mozilla/js/src/jsapi.h /js/src/jsapi.h ... npl/gpl found ... license block lines: 2-32 ... original code is: Mozilla Communicator client code ... initially by: Original Code is Netscape Communications Corporation (1998) (2) Gather and dump statistics on the processed files: $ ./relic.py -s mozilla/js/src/jsapi.h Summary of Licenses in Files ============================ Number Percent License ------- -------- ----------- 1 100.00% npl/gpl ---------------------------- 1 files processed Licensed files with complete tri-license block: 0 Licensed files with no 'Initial Developer...' info: 0 Licensed files with no 'Original Code is...' info: 0 Licensed files with improperly indented 'Contributor(s):' line(s): 0 (3) Re-licensing the given files that need it (i.e. files with a complete and correct license block are changed). $ ./relic.py -r mozilla/js/src/jsapi.h mozilla/js/src/jsapi.h ... npl/gpl found, need to relicense ... original code is: Mozilla Communicator client code ... initially by: Original Code is Netscape Communications Corporation (1998) ... replacing lines 2-32 with NPL/GPL/LGPL tri-license ... backing up to 'mozilla/js/src/jsapi.h~0' ... done relicensing 'mozilla/js/src/jsapi.h' --------------------- Summary of Results ------------------------ Files skipped b/c they are binary: 0 Files skipped b/c they already had proper license: 0 Files skipped b/c they had no license: 0 Files re-licensed: 1 ----------------------------------------------------------------- If you are trying this as you read this, run the following command to see the changes made to jsapi.h: $ diff -c mozilla/js/src/jsapi.h~0 mozilla/js/src/jsapi.h What Files are Processed: 'relic.py' will process any files listed on the command line and will recursively process all files in any given directories: $ ./relic.py -s mozilla/js/src Summary of Licenses in Files ============================ Number Percent License ------- -------- ----------- 324 74.14% npl/gpl 71 16.25% <none found> 23 5.26% mpl/gpl/lgpl 4 0.92% npl/gpl/lgpl 4 0.92% mpl 4 0.92% ibm 3 0.69% mpl/gpl 2 0.46% npl 2 0.46% <unknown license> ---------------------------- 437 files processed Licensed files with complete tri-license block: 27 Licensed files with no 'Initial Developer...' info: 1 Licensed files with no 'Original Code is...' info: 27 Licensed files with improperly indented 'Contributor(s):' line(s): 2 The following files are automatically skipped: - CVS control directories; - files listed in .cvsignore files; - all *.s files (there usage of comment delimiters is all over the map); - binary files; and - any files included in the following global variables in relic.py: _g_skip_file_basenames, _g_skip_files, _g_skip_dir_basenames, _g_skip_dirs, _g_skip_ext. Error Handling (--force): There are some situations that relic.py cannot handle. E.g., a file with no license block to start with, an IBM license block, a license block sufficiently strange enough to baffle relic.py regular expressions. In normal operation, when an error is encoutered on any file processing stops. This can be annoying, so a --force|-f option was added to force relic.py to continue processing files after an error with a file is encountered. In all modes of operation errors are summarized at the end. $ ./relic.py -s mozilla/extensions/transformiix/source/xml ERROR:relic:This is line is part of the 'Contributor(s):' paragraph but (1) is not indented and (2) does not look like it contains an email address: mozilla/extensions/transformiix/source/xml/XMLDOMUtils.h:20: ' * Keith Visco' (the --force option can be used to skip problematic files and continue processing rather than aborting) $ ./relic.py -sf mozilla/extensions/transformiix/source/xml Summary of Licenses in Files ============================ Number Percent License ------- -------- ----------- 24 100.00% mpl ---------------------------- 24 files processed Licensed files with complete tri-license block: 0 Licensed files with no 'Initial Developer...' info: 16 Licensed files with no 'Original Code is...' info: 15 Licensed files with improperly indented 'Contributor(s):' line(s): 3 =================== Summary of Errors =========================== Files with processing errors: 3 ================================================================= mozilla/extensions/transformiix/source/xml/XMLDOMUtils.cpp: This is line is part of the 'Contributor(s):' paragraph but (1) is not indented and (2) does not look like it contains an email address: mozilla/extensions/transformiix/source/xml/XMLDOMUtils.cpp:20: ' * Keith Visco ' mozilla/extensions/transformiix/source/xml/XMLDOMUtils.h: This is line is part of the 'Contributor(s):' paragraph but (1) is not indented and (2) does not look like it contains an email address: mozilla/extensions/transformiix/source/xml/XMLDOMUtils.h:20: ' * Keith Visco ' mozilla/extensions/transformiix/source/xml/parser/txXMLParser.h: This is line is part of the 'Contributor(s):' paragraph but (1) is not indented and (2) does not look like it contains an email address: mozilla/extensions/transformiix/source/xml/parser/txXMLParser.h:20: ' * Tom Kneeland' ================================================================= Unfinished Business: The following is a list of issues that should be sorted out before this should be used to start making patches to the Mozilla tree: - What to do for files that have no 'Initial Developer...' block? - What to do for files that have no 'Original Code is...' block? - Are there specific files or parts of the mozilla tree that should be skipped always, i.e. generated files, files not meant to have leading license blocks? - What to do for files with the IBM license? - Should *.uf be ignored (there are 87 of them in the mozilla tree)? - The 'ripl' and lick' scripts' "include licenses" configuration option is not supported in anyway by relic.py. Is it necessary? I don't see a useful use case. - test/x_thread_align_center.xml and test/abs2rel.pl are examples of files that are not handled correctly. In the former there is some data loss. In the latter the is some cruft left over. Contributors: Trent Mick (TrentM@ActiveState.com) originally wrote this script, borrowing some from earlier attempts in the name of 'lick', 'lutils.py', and 'ripl' (see <http://bugzilla.mozilla.org/show_bug.cgi?id=98089>). If you have problems with the script please let me know and hopefully I can help you out.