src/third_party/chromite/licensing/licenses.py

   1 # Copyright (c) 2012 The Chromium OS Authors. All rights reserved.
   2 # Use of this source code is governed by a BSD-style license that can be
   3 # found in the LICENSE file.
   4
   5 """Generate an HTML file containing license info for all installed packages.
   6
   7 Documentation on this script is also available here:
   8 http://www.chromium.org/chromium-os/licensing-for-chromiumos-developers
   9
  10 End user (i.e. package owners) documentation is here:
  11 http://www.chromium.org/chromium-os/licensing-for-chromiumos-package-owners
  12
  13 Usage:
  14 For this script to work, you must have built the architecture
  15 this is being run against, _after_ you've last run repo sync.
  16 Otherwise, it will query newer source code and then fail to work on packages
  17 that are out of date in your build.
  18
  19 Recommended build:
  20   cros_sdk
  21   export BOARD=x86-alex
  22   sudo rm -rf /build/$BOARD
  23   cd ~/trunk/src/scripts
  24   # If you wonder why we need to build Chromium OS just to run
  25   # `emerge -p -v virtual/target-os` on it, we don't.
  26   # However, later we run ebuild unpack, and this will apply patches and run
  27   # configure. Configure will fail due to aclocal macros missing in
  28   # /build/x86-alex/usr/share/aclocal (those are generated during build).
  29   # This will take about 10mn on a Z620.
  30   ./build_packages --board=$BOARD --nowithautotest --nowithtest --nowithdev
  31                    --nowithfactory
  32   cd ~/trunk/chromite/licensing
  33   # This removes left over packages from an earlier build that could cause
  34   # conflicts.
  35   eclean-$BOARD packages
  36   %(prog)s [--debug] [--all-packages] --board $BOARD [-o o.html] 2>&1 | tee out
  37
  38 The workflow above is what you would do to generate a licensing file by hand
  39 given a chromeos tree.
  40 Note that building packages now creates a license.yaml fork in the package
  41 which you can see with
  42 qtbz2 -x -O  /build/x86-alex/packages/dev-util/libc-bench-0.0.1-r8.tbz2 |
  43      qxpak -x -O - license.yaml
  44 This gets automatically installed in
  45 /build/x86-alex/var/db/pkg/dev-util/libc-bench-0.0.1-r8/license.yaml
  46
  47 Unless you run with --generate, the script will now gather those license
  48 bits and generate a license file from there.
  49 License bits for each package are generated by default from
  50 src/scripts/hooks/install/gen-package-licenses.sh which gets run automatically
  51 by emerge as part of a package build (by running this script with
  52 --hook /path/to/tmp/portage/build/tree/for/that/package
  53
  54 If license bits are missing, they are generated on the fly if you were running
  55 with sudo. If you didn't use sudo, this on the fly late generation will fail
  56 and act as a warning that your prebuilts were missing package build time
  57 licenses.
  58
  59 You can check the licenses and/or generate a HTML file for a list of
  60 packages using --package or -p:
  61   %(prog)s --package "dev-libs/libatomic_ops-7.2d" --package
  62   "net-misc/wget-1.14" --board $BOARD -o out.html
  63
  64 Note that you'll want to use --generate to force regeneration of the licensing
  65 bits from a package source you may have just modified but not rebuilt.
  66
  67 If you want to check licensing against all ChromeOS packages, you should
  68 run ./build_packages --board=$BOARD to build everything and then run
  69 this script with --all-packages.
  70
  71 By default, when no package is specified, this script processes all
  72 packages for $BOARD. The output HTML file is meant to update
  73 http://src.chromium.org/viewvc/chrome/trunk/src/chrome/browser/resources/ +
  74   chromeos/about_os_credits.html?view=log
  75 (gclient config svn://svn.chromium.org/chrome/trunk/src)
  76 For an example CL, see https://codereview.chromium.org/13496002/
  77
  78 The detailed process is listed below.
  79
  80 * Check out the branch you intend to generate the HTML file for. Use
  81   the internal manifest for this purpose.
  82     repo init -b <branch_name> -u <URL>
  83
  84   The list of branches (e.g. release-R33-5116.B) are available here:
  85   https://chromium.googlesource.com/chromiumos/manifest/+refs
  86
  87 * Generate the HTML file by following the steps mentioned
  88   previously. Check whether your changes are valid with:
  89     bin/diff_license_html output.html-M33 output.html-M34
  90   and review the diff.
  91
  92 * Update the about_os_credits.html in the svn repository. Create a CL
  93   and upload it for review.
  94     gcl change <change_name>
  95     gcl upload <change_name>
  96
  97   When uploading, you may get a warning for file being too large to
  98   upload. In this case, your CL can still be reviewed. Always include
  99   the diff in your commit message so that the reviewers know what the
 100   changes are. You can add reviewers on the review page by clicking on
 101   "Edit issue".  (A quick reference:
 102   http://www.chromium.org/developers/quick-reference)
 103
 104   Make sure you click on 'Publish+Mail Comments' after adding reviewers
 105   (the review URL looks like this https://codereview.chromium.org/183883018/ ).
 106
 107 * After receiving LGTMs, commit your change with 'gcl commit <change_name>'.
 108
 109 If you don't get this in before the freeze window, it'll need to be merged into
 110 the branch being released, which is done by adding a Merge-Requested label.
 111 Once it's been updated to "Merge-Approved" by a TPM, please merge into the
 112 required release branch. You can ask karen@ for merge approve help.
 113 Example: http://crbug.com/221281
 114
 115 Note however that this is only during the transition period.
 116 build-image will be modified to generate the license for each board and save
 117 the file in /opt/google/chrome/resources/about_os_credits.html or as defined
 118 in http://crbug.com/271832 .
 119 """
 120
 121 from __future__ import print_function
 122
 123 import logging
 124 import os
 125
 126 from chromite.lib import commandline
 127 from chromite.lib import cros_build_lib
 128
 129 from chromite.licensing import licenses_lib
 130
 131 # These packages exist as workarounds....
 132 #
 133 # X is listed to avoid installing licensing info for all split X packages.
 134 # sys-boot packages are listed as a partial work around for not having per-board
 135 # credits files (TODO(dgarrett): Remove when crbug.com/197970 fixed).
 136 EXTRA_PACKAGES = (
 137     ('x11-base/X-Org-1.9.3', ['http://www.x.org/'], ['X']),
 138     ('sys-kernel/Linux-2.6', ['http://www.kernel.org/'], ['GPL-2']),
 139     ('sys-boot/u-boot-2013.06', ['http://www.denx.de/wiki/U-Boot'], ['GPL-2']),
 140     ('sys-boot/coreboot-2013.04', ['http://www.coreboot.org/'], ['GPL-2']),
 141 )
 142
 143
 144 def LoadPackageInfo(board, all_packages, generateMissing, packages):
 145   """Do the work when we're not called as a hook."""
 146   logging.info("Using board %s.", board)
 147
 148   builddir = os.path.join(cros_build_lib.GetSysroot(board=board),
 149                           'tmp', 'portage')
 150
 151   if not os.path.exists(builddir):
 152     raise AssertionError(
 153         "FATAL: %s missing.\n"
 154         "Did you give the right board and build that tree?" % builddir)
 155
 156   detect_packages = not packages
 157   if detect_packages:
 158     # If no packages were specified, we look up the full list.
 159     packages = licenses_lib.ListInstalledPackages(board, all_packages)
 160
 161   if not packages:
 162     raise AssertionError('FATAL: Could not get any packages for board %s' %
 163                          board)
 164
 165   logging.debug("Initial Package list to work through:\n%s",
 166                 '\n'.join(sorted(packages)))
 167   licensing = licenses_lib.Licensing(board, packages, generateMissing)
 168
 169   licensing.LoadPackageInfo()
 170   logging.debug("Package list to skip:\n%s",
 171                 '\n'.join([p for p in sorted(packages)
 172                            if licensing.packages[p].skip]))
 173   logging.debug("Package list left to work through:\n%s",
 174                 '\n'.join([p for p in sorted(packages)
 175                            if not licensing.packages[p].skip]))
 176   licensing.ProcessPackageLicenses()
 177   if detect_packages:
 178     # If we detected 'all' packages, we have to add in these extras.
 179     for fullnamewithrev, homepages, license_names in EXTRA_PACKAGES:
 180       licensing.AddExtraPkg(fullnamewithrev, homepages, license_names)
 181
 182   return licensing
 183
 184
 185 def main(args):
 186   parser = commandline.ArgumentParser(usage=__doc__)
 187   parser.add_argument("-b", "--board",
 188                       help="which board to run for, like x86-alex")
 189   parser.add_argument("-p", "--package", action="append", default=[],
 190                       dest="packages",
 191                       help="check the license of the package, e.g.,"
 192                       "dev-libs/libatomic_ops-7.2d")
 193   parser.add_argument("-a", "--all-packages", action="store_true",
 194                       dest="all_packages",
 195                       help="Run licensing against all packages in the "
 196                       "build tree, instead of just virtual/target-os "
 197                       "dependencies.")
 198   parser.add_argument("-g", "--generate-licenses", action="store_true",
 199                       dest="gen_licenses",
 200                       help="Generate license information, if missing.")
 201   parser.add_argument("-o", "--output", type="path",
 202                       help="which html file to create with output")
 203   opts = parser.parse_args(args)
 204
 205
 206   if not opts.board:
 207     raise AssertionError("No board given (--board)")
 208
 209   if not opts.output and not opts.gen_licenses:
 210     raise AssertionError("You must specify --output and/or --generate-licenses")
 211
 212   if opts.gen_licenses and os.geteuid() != 0:
 213     raise AssertionError("Run with sudo if you use --generate-licenses.")
 214
 215   licensing = LoadPackageInfo(
 216       opts.board, opts.all_packages, opts.gen_licenses, opts.packages)
 217
 218   if opts.output:
 219     licensing.GenerateHTMLLicenseOutput(opts.output)