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.
20db9ee22b