build-aux/vcs_to_changelog.py

   1 #!/usr/bin/python3
   2 # Main VCSToChangeLog script.
   3 # Copyright (C) 2019 Free Software Foundation, Inc.
   4 #
   5 # This program is free software: you can redistribute it and/or modify
   6 # it under the terms of the GNU General Public License as published by
   7 # the Free Software Foundation; either version 3 of the License, or
   8 # (at your option) any later version.
   9 #
  10 # This program is distributed in the hope that it will be useful,
  11 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 # GNU General Public License for more details.
  14 #
  15 # You should have received a copy of the GNU General Public License
  16 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
  17
  18 ''' Generate a ChangeLog style output based on a VCS log.
  19
  20 This script takes two revisions as input and generates a ChangeLog style output
  21 for all revisions between the two revisions.
  22
  23 This script is intended to be executed from the project parent directory.
  24
  25 The vcstocl directory has a file vcstocl_quirks.py that defines a
  26 function called get_project_quirks that returns a object of class type
  27 ProjectQuirks or a subclass of the same.  The definition of the ProjectQuirks
  28 class is below and it specifies the properties that the project must set to
  29 ensure correct parsing of its contents.
  30
  31 Among other things, ProjectQurks specifies the VCS to read from; the default is
  32 assumed to be git.  The script then studies the VCS log and for each change,
  33 list out the nature of changes in the constituent files.
  34
  35 Each file type may have parser frontends that can read files and construct
  36 objects that may be compared to determine the minimal changes that occured in
  37 each revision.  For files that do not have parsers, we may only know the nature
  38 of changes at the top level depending on the information that the VCS stores.
  39
  40 The parser frontend must have a compare() method that takes the old and new
  41 files as arrays of strings and prints the output in ChangeLog format.
  42
  43 Currently implemented VCS:
  44
  45     git
  46
  47 Currently implemented frontends:
  48
  49     C
  50 '''
  51 import sys
  52 import os
  53 import re
  54 import argparse
  55 from vcstocl.misc_util import *
  56 from vcstocl import frontend_c
  57 from vcstocl.vcs_git import *
  58
  59 debug = DebugUtil(False)
  60
  61 class ProjectQuirks:
  62     # This is a list of regex substitutions for C/C++ macros that are known to
  63     # break parsing of the C programs.  Each member of this list is a dict with
  64     # the key 'orig' having the regex and 'sub' having the substitution of the
  65     # regex.
  66     MACRO_QUIRKS = []
  67
  68     # This is a list of macro definitions that are extensively used and are
  69     # known to break parsing due to some characteristic, mainly the lack of a
  70     # semicolon at the end.
  71     C_MACROS = []
  72
  73     # The repo type, defaults to git.
  74     repo = 'git'
  75
  76     # List of files to ignore either because they are not needed (such as the
  77     # ChangeLog) or because they are non-parseable.  For example, glibc has a
  78     # header file that is only assembly code, which breaks the C parser.
  79     IGNORE_LIST = ['ChangeLog']
  80
  81
  82 # Load quirks file.  We assume that the script is run from the top level source
  83 # directory.
  84 sys.path.append('/'.join([os.path.dirname(os.path.realpath(__file__)),
  85                 'vcstocl']))
  86 try:
  87     from vcstocl_quirks import *
  88     project_quirks = get_project_quirks(debug)
  89 except:
  90     project_quirks = ProjectQuirks()
  91
  92
  93 def main(repo, frontends, refs):
  94     ''' ChangeLog Generator Entry Point.
  95     '''
  96     commits = repo.list_commits(args.refs)
  97     for commit in commits:
  98         repo.list_changes(commit, frontends)
  99
 100
 101 if __name__ == '__main__':
 102     parser = argparse.ArgumentParser()
 103
 104     parser.add_argument('refs', metavar='ref', type=str, nargs=2,
 105                      help='Refs to print ChangeLog entries between')
 106
 107     parser.add_argument('-d', '--debug', required=False, action='store_true',
 108                      help='Run the file parser debugger.')
 109
 110     args = parser.parse_args()
 111
 112     debug.debug = args.debug
 113
 114     if len(args.refs) < 2:
 115         debug.eprint('Two refs needed to get a ChangeLog.')
 116         sys.exit(os.EX_USAGE)
 117
 118     REPO = {'git': GitRepo(project_quirks.IGNORE_LIST, debug)}
 119
 120     fe_c = frontend_c.Frontend(project_quirks, debug)
 121     FRONTENDS = {'.c': fe_c,
 122                  '.h': fe_c}
 123
 124     main(REPO[project_quirks.repo], FRONTENDS, args.refs)