| 1 |
#!/usr/bin/python |
| 2 |
# -*- coding: utf-8 -*- |
| 3 |
# |
| 4 |
# Copyright © 2015 Collabora Ltd. |
| 5 |
# |
| 6 |
# This library is free software; you can redistribute it and/or modify it under |
| 7 |
# the terms of the GNU Lesser General Public License as published by the Free |
| 8 |
# Software Foundation; either version 2.1 of the License, or (at your option) |
| 9 |
# any later version. |
| 10 |
# |
| 11 |
# This library is distributed in the hope that it will be useful, but WITHOUT |
| 12 |
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS |
| 13 |
# FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more |
| 14 |
# details. |
| 15 |
# |
| 16 |
# You should have received a copy of the GNU Lesser General Public License |
| 17 |
# along with this library. If not, see <http://www.gnu.org/licenses/>. |
| 18 |
|
| 19 |
""" |
| 20 |
Wrapper around dbus-interface-diff to integrate it with a VCS |
| 21 |
|
| 22 |
This implements an API signature database in the project’s version control |
| 23 |
system so that all users of the VCS can do API compatibility between all past |
| 24 |
signed releases. Currently, only git is supported. |
| 25 |
|
| 26 |
Requirements: |
| 27 |
• Support out-of-tree builds, where srcdir ≠ builddir. |
| 28 |
• Support bare repositories, or where GIT_WORK_TREE ≠ .git. |
| 29 |
• Exit with status 0 if GIT_DIR does not exist; support the use case of |
| 30 |
running `make distcheck` inside an extracted release tarball. |
| 31 |
• Support both tag-before-dist and tag-after-dist workflows. |
| 32 |
""" |
| 33 |
|
| 34 |
import argparse |
| 35 |
from contextlib import contextmanager |
| 36 |
import os |
| 37 |
import pipes |
| 38 |
import shlex |
| 39 |
import shutil |
| 40 |
import subprocess |
| 41 |
import sys |
| 42 |
import tempfile |
| 43 |
|
| 44 |
|
| 45 |
@contextmanager |
| 46 |
def named_pipe(): |
| 47 |
"""Create and cleanup a named pipe in a temporary directory.""" |
| 48 |
dirname = tempfile.mkdtemp() |
| 49 |
try: |
| 50 |
path = os.path.join(dirname, 'fifo') |
| 51 |
os.mkfifo(path) |
| 52 |
yield path |
| 53 |
finally: |
| 54 |
shutil.rmtree(dirname) |
| 55 |
|
| 56 |
|
| 57 |
def _git_command(args, command): |
| 58 |
"""Build a git command line with standard arguments.""" |
| 59 |
out = [args.git] |
| 60 |
if args.git_dir != '': |
| 61 |
out += ['--git-dir', args.git_dir] |
| 62 |
if args.git_work_tree != '': |
| 63 |
out += ['--work-tree', args.git_work_tree] |
| 64 |
|
| 65 |
return out + [command] |
| 66 |
|
| 67 |
|
| 68 |
def _format_command(args): |
| 69 |
"""Local wrapper for pipes.quote() with support for Python 2.7.""" |
| 70 |
try: |
| 71 |
# pylint: disable=no-member |
| 72 |
return ' '.join(shlex.quote(a) for a in args) |
| 73 |
except AttributeError: |
| 74 |
try: |
| 75 |
# pylint: disable=no-member |
| 76 |
return ' '.join(pipes.quote(a) for a in args) |
| 77 |
except AttributeError: |
| 78 |
# Give up |
| 79 |
return ' '.join(args) |
| 80 |
|
| 81 |
|
| 82 |
def _get_contents_of_file(args, tag, api_xml_file): |
| 83 |
"""Get the git object ID of api_xml_file in the tag revision.""" |
| 84 |
rev = subprocess.check_output(_git_command(args, 'rev-parse') + |
| 85 |
['--verify', '--quiet', |
| 86 |
'%s^{tag}:%s' % (tag, api_xml_file)]) |
| 87 |
return rev.strip().decode('utf-8') |
| 88 |
|
| 89 |
|
| 90 |
def _set_notes_for_ref(args, tag, api_xml_basename, notes): |
| 91 |
"""Store the notes object ID as api_xml_basename in the tag revision.""" |
| 92 |
with open(os.devnull, 'w') as dev_null: |
| 93 |
subprocess.check_output(_git_command(args, 'notes') + |
| 94 |
['--ref', |
| 95 |
'refs/%s/%s' % |
| 96 |
(args.dbus_api_git_refs, api_xml_basename), |
| 97 |
'add', '-C', notes, tag], |
| 98 |
stderr=dev_null) |
| 99 |
|
| 100 |
|
| 101 |
def _notes_exist_for_ref(args, tag, api_xml_basename): |
| 102 |
"""Check whether notes have already been stored for this file and tag.""" |
| 103 |
with open(os.devnull, 'w') as dev_null: |
| 104 |
status = subprocess.call(_git_command(args, 'notes') + |
| 105 |
['--ref', |
| 106 |
'refs/%s/%s' % |
| 107 |
(args.dbus_api_git_refs, api_xml_basename), |
| 108 |
'show', tag], |
| 109 |
stdout=dev_null, |
| 110 |
stderr=dev_null) |
| 111 |
return status == 0 |
| 112 |
|
| 113 |
|
| 114 |
def _get_notes_filename_for_head(args, api_xml_basename): |
| 115 |
"""Get the filename of api_xml_basename in the git work tree.""" |
| 116 |
filename = subprocess.check_output(_git_command(args, 'ls-files') + |
| 117 |
['--full-name', |
| 118 |
'*/%s' % api_xml_basename]) |
| 119 |
filename = filename.strip().decode('utf-8') |
| 120 |
|
| 121 |
# Resolve the relative path against the work tree. |
| 122 |
if args.git_work_tree != '': |
| 123 |
filename = os.path.join(args.git_work_tree, filename) |
| 124 |
|
| 125 |
return filename |
| 126 |
|
| 127 |
|
| 128 |
def _fetch_notes(args): |
| 129 |
"""Fetch the latest API signature database from the remote.""" |
| 130 |
subprocess.check_output(_git_command(args, 'fetch') + |
| 131 |
[args.git_remote_origin, |
| 132 |
'refs/%s/*:refs/%s/*' % |
| 133 |
(args.dbus_api_git_refs, args.dbus_api_git_refs)]) |
| 134 |
|
| 135 |
|
| 136 |
def _push_notes(args): |
| 137 |
"""Push the local API signature database to the remote.""" |
| 138 |
command = _git_command(args, 'push') |
| 139 |
command += [args.git_remote_origin, |
| 140 |
'refs/' + args.dbus_api_git_refs + '/*'] |
| 141 |
|
| 142 |
if not args.no_push: |
| 143 |
subprocess.check_output(command) |
| 144 |
else: |
| 145 |
sys.stdout.write('Run this command to push the API signature ' |
| 146 |
'database:\n' |
| 147 |
' %s\n' % _format_command(command)) |
| 148 |
|
| 149 |
|
| 150 |
def _is_release(args, ref): |
| 151 |
"""Check whether ref identifies a signed tag.""" |
| 152 |
with open(os.devnull, 'w') as dev_null: |
| 153 |
code = subprocess.call(_git_command(args, 'rev-parse') + |
| 154 |
['--verify', ref], |
| 155 |
stdout=dev_null, stderr=dev_null) |
| 156 |
return code == 0 |
| 157 |
|
| 158 |
|
| 159 |
def _get_latest_release(args): |
| 160 |
"""Get the name of the latest signed tag.""" |
| 161 |
tag_list = subprocess.check_output(_git_command(args, 'rev-list') + |
| 162 |
['--tags', '--max-count=1']) |
| 163 |
tag_list = tag_list.strip().decode('utf-8').split('\n') |
| 164 |
latest_tag = subprocess.check_output(_git_command(args, 'describe') + |
| 165 |
['--tags'] + tag_list) |
| 166 |
|
| 167 |
return latest_tag.strip().decode('utf-8') |
| 168 |
|
| 169 |
|
| 170 |
def command_dist(args): |
| 171 |
"""Store the current API signature against the latest signed tag.""" |
| 172 |
# Get the latest git tag |
| 173 |
try: |
| 174 |
latest_tag = _get_latest_release(args) |
| 175 |
except subprocess.CalledProcessError: |
| 176 |
sys.stderr.write('error: Failed to find latest git tag: %s.') |
| 177 |
return 1 |
| 178 |
|
| 179 |
# Store notes for each API file |
| 180 |
for api_xml_file in args.dbus_api_xml_files: |
| 181 |
try: |
| 182 |
api_xml_basename = os.path.basename(api_xml_file) |
| 183 |
|
| 184 |
# Do notes already exist for this file and tag? |
| 185 |
if args.ignore_existing and \ |
| 186 |
_notes_exist_for_ref(args, latest_tag, api_xml_basename): |
| 187 |
sys.stdout.write('%s: Ignored XML file ‘%s’; already has ' |
| 188 |
'a note\n' % |
| 189 |
(latest_tag, api_xml_basename)) |
| 190 |
continue |
| 191 |
|
| 192 |
notes = _get_contents_of_file(args, latest_tag, api_xml_file) |
| 193 |
subprocess.check_output(_git_command(args, 'notes') + |
| 194 |
['--ref', |
| 195 |
'refs/%s/%s' % |
| 196 |
(args.dbus_api_git_refs, |
| 197 |
api_xml_basename), |
| 198 |
'add', '-C', notes, latest_tag]) |
| 199 |
|
| 200 |
sys.stdout.write('%s: Added note ‘%s’ for XML file ‘%s’\n' % |
| 201 |
(latest_tag, notes, api_xml_basename)) |
| 202 |
except subprocess.CalledProcessError: |
| 203 |
sys.stderr.write('error: Failed to store notes for API file ' |
| 204 |
'‘%s’ and git tag ‘%s’.\n' % |
| 205 |
(api_xml_file, latest_tag)) |
| 206 |
return 1 |
| 207 |
|
| 208 |
# Push to the remote |
| 209 |
try: |
| 210 |
_push_notes(args) |
| 211 |
except subprocess.CalledProcessError: |
| 212 |
sys.stderr.write('error: Failed to push notes to remote ‘%s’.\n' % |
| 213 |
args.git_remote_origin) |
| 214 |
return 1 |
| 215 |
|
| 216 |
return 0 |
| 217 |
|
| 218 |
|
| 219 |
# pylint: disable=too-many-locals,too-many-branches,too-many-statements |
| 220 |
def command_check(args): |
| 221 |
""" |
| 222 |
Check for API differences between two tags. |
| 223 |
|
| 224 |
If old_ref is not specified, it defaults to the latest signed tag. If |
| 225 |
new_ref is not specified, it defaults to the git work tree. |
| 226 |
""" |
| 227 |
if args.old_ref != '' and not _is_release(args, args.old_ref): |
| 228 |
sys.stderr.write('error: Invalid --old-ref ‘%s’\n' % args.old_ref) |
| 229 |
return 1 |
| 230 |
|
| 231 |
if args.new_ref != '' and not _is_release(args, args.new_ref): |
| 232 |
sys.stderr.write('error: Invalid --new-ref ‘%s’\n' % args.new_ref) |
| 233 |
return 1 |
| 234 |
|
| 235 |
try: |
| 236 |
_fetch_notes(args) |
| 237 |
except subprocess.CalledProcessError: |
| 238 |
# Continue anyway |
| 239 |
sys.stderr.write('error: Failed to fetch latest refs.\n') |
| 240 |
|
| 241 |
old_ref = args.old_ref |
| 242 |
new_ref = args.new_ref |
| 243 |
|
| 244 |
if old_ref == '': |
| 245 |
# Get the latest git tag |
| 246 |
try: |
| 247 |
old_ref = _get_latest_release(args) |
| 248 |
except subprocess.CalledProcessError: |
| 249 |
sys.stderr.write('error: Failed to find latest git tag.\n') |
| 250 |
return 1 |
| 251 |
|
| 252 |
try: |
| 253 |
refs = subprocess.check_output(_git_command(args, 'for-each-ref') + |
| 254 |
['--format=%(refname)', |
| 255 |
'refs/%s' % args.dbus_api_git_refs]) |
| 256 |
refs = refs.strip().decode('utf-8').split('\n') |
| 257 |
except subprocess.CalledProcessError: |
| 258 |
sys.stderr.write('error: Failed to get ref list.\n') |
| 259 |
return 1 |
| 260 |
|
| 261 |
retval = 0 |
| 262 |
|
| 263 |
for note_ref in refs: |
| 264 |
api_xml_basename = os.path.basename(note_ref) |
| 265 |
|
| 266 |
if args.silent: |
| 267 |
sys.stdout.write(' DIFF %s\n' % api_xml_basename) |
| 268 |
else: |
| 269 |
sys.stdout.write('Comparing %s\n' % api_xml_basename) |
| 270 |
|
| 271 |
with named_pipe() as old_pipe_path, named_pipe() as new_pipe_path: |
| 272 |
old_notes_filename = old_pipe_path |
| 273 |
|
| 274 |
if new_ref == '': |
| 275 |
new_notes_filename = \ |
| 276 |
_get_notes_filename_for_head(args, api_xml_basename) |
| 277 |
else: |
| 278 |
new_notes_filename = new_pipe_path |
| 279 |
|
| 280 |
diff_command = ['dbus-interface-diff', |
| 281 |
'--warnings', args.warnings, |
| 282 |
'--file-display-name', api_xml_basename] |
| 283 |
if args.fatal_warnings: |
| 284 |
diff_command += ['--fatal-warnings'] |
| 285 |
diff_command += [old_notes_filename, new_notes_filename] |
| 286 |
old_notes_command = _git_command(args, 'notes') + [ |
| 287 |
'--ref', |
| 288 |
'refs/%s/%s' % (args.dbus_api_git_refs, api_xml_basename), |
| 289 |
'show', old_ref, |
| 290 |
] |
| 291 |
new_notes_command = _git_command(args, 'notes') + [ |
| 292 |
'--ref', |
| 293 |
'refs/%s/%s' % (args.dbus_api_git_refs, api_xml_basename), |
| 294 |
'show', new_ref, |
| 295 |
] |
| 296 |
|
| 297 |
diff_proc = subprocess.Popen(diff_command) |
| 298 |
|
| 299 |
with open(old_pipe_path, 'wb') as old_pipe, \ |
| 300 |
open(os.devnull, 'w') as dev_null: |
| 301 |
old_notes_proc = subprocess.Popen(old_notes_command, |
| 302 |
stdout=old_pipe, |
| 303 |
stderr=dev_null) |
| 304 |
|
| 305 |
if new_ref == '': |
| 306 |
new_notes_proc = None |
| 307 |
|
| 308 |
# Debug output. Roughly equivalent to `set -v`. |
| 309 |
if not args.silent: |
| 310 |
ls_files_command = _git_command(args, 'ls-files') + [ |
| 311 |
'--full-name', |
| 312 |
'*/%s' % api_xml_basename, |
| 313 |
] |
| 314 |
|
| 315 |
if args.git_work_tree != '': |
| 316 |
git_work_tree = args.git_work_tree + '/' |
| 317 |
else: |
| 318 |
git_work_tree = '' |
| 319 |
|
| 320 |
sys.stdout.write('%s \\\n' |
| 321 |
' <(%s) \\\n' |
| 322 |
' %s`%s`\n' % |
| 323 |
(_format_command(diff_command[:-2]), |
| 324 |
_format_command(old_notes_command), |
| 325 |
git_work_tree, |
| 326 |
_format_command(ls_files_command))) |
| 327 |
else: |
| 328 |
with open(new_pipe_path, 'wb') as new_pipe: |
| 329 |
new_notes_proc = subprocess.Popen(new_notes_command, |
| 330 |
stdout=new_pipe, |
| 331 |
stderr=dev_null) |
| 332 |
|
| 333 |
# Debug output. Roughly equivalent to `set -v`. |
| 334 |
if not args.silent: |
| 335 |
sys.stdout.write('%s \\\n' |
| 336 |
' <(%s) \\\n' |
| 337 |
' <(%s)\n' % |
| 338 |
(_format_command(diff_command[:-2]), |
| 339 |
_format_command(old_notes_command), |
| 340 |
_format_command(new_notes_command))) |
| 341 |
|
| 342 |
old_notes_proc.communicate() |
| 343 |
old_notes_proc.wait() |
| 344 |
|
| 345 |
if new_notes_proc is not None: |
| 346 |
new_notes_proc.wait() |
| 347 |
|
| 348 |
diff_proc.wait() |
| 349 |
|
| 350 |
# Output the status from the first failure |
| 351 |
if retval == 0 and diff_proc.returncode != 0: |
| 352 |
retval = diff_proc.returncode |
| 353 |
|
| 354 |
return retval |
| 355 |
|
| 356 |
|
| 357 |
def command_install(args): |
| 358 |
"""Set up the API signature database for all existing signed tags.""" |
| 359 |
try: |
| 360 |
tag_list = subprocess.check_output(_git_command(args, 'tag')) |
| 361 |
tag_list = tag_list.strip().decode('utf-8').split('\n') |
| 362 |
except subprocess.CalledProcessError: |
| 363 |
sys.stderr.write('error: Failed to get tag list.\n') |
| 364 |
return 1 |
| 365 |
|
| 366 |
for tag in tag_list: |
| 367 |
outputted = False |
| 368 |
|
| 369 |
for api_xml_file in args.dbus_api_xml_files: |
| 370 |
api_xml_basename = os.path.basename(api_xml_file) |
| 371 |
|
| 372 |
try: |
| 373 |
notes = _get_contents_of_file(args, tag, api_xml_file) |
| 374 |
except subprocess.CalledProcessError: |
| 375 |
# Ignore it. |
| 376 |
notes = '' |
| 377 |
|
| 378 |
if notes == '': |
| 379 |
continue |
| 380 |
|
| 381 |
try: |
| 382 |
_set_notes_for_ref(args, tag, api_xml_basename, notes) |
| 383 |
|
| 384 |
sys.stdout.write('%s: Added note ‘%s’ for XML file ‘%s’\n' % |
| 385 |
(tag, notes, api_xml_basename)) |
| 386 |
outputted = True |
| 387 |
except subprocess.CalledProcessError: |
| 388 |
# Ignore it |
| 389 |
continue |
| 390 |
|
| 391 |
if not outputted: |
| 392 |
sys.stdout.write('%s: Nothing to do\n' % tag) |
| 393 |
|
| 394 |
# Push the new refs |
| 395 |
try: |
| 396 |
_push_notes(args) |
| 397 |
except subprocess.CalledProcessError: |
| 398 |
sys.stderr.write('error: Failed to push notes to remote ‘%s’.\n' % |
| 399 |
args.git_remote_origin) |
| 400 |
return 1 |
| 401 |
|
| 402 |
return 0 |
| 403 |
|
| 404 |
|
| 405 |
def main(): |
| 406 |
"""Main helper implementation.""" |
| 407 |
# Parse command line arguments. |
| 408 |
parser = argparse.ArgumentParser( |
| 409 |
description='Comparing D-Bus interface definitions') |
| 410 |
|
| 411 |
# Common arguments |
| 412 |
parser.add_argument('--silent', action='store_const', const=True, |
| 413 |
default=False, |
| 414 |
help='Silence all non-error output') |
| 415 |
parser.add_argument('--git', type=str, default='git', metavar='COMMAND', |
| 416 |
help='Path to the git command, including extra ' |
| 417 |
'arguments') |
| 418 |
parser.add_argument('--git-dir', type=str, default='', metavar='PATH', |
| 419 |
help='Path to the git directory in the project ' |
| 420 |
'checkout') |
| 421 |
parser.add_argument('--git-work-tree', type=str, default='', |
| 422 |
metavar='PATH', |
| 423 |
help='Path to the git work tree for the project') |
| 424 |
parser.add_argument('--git-remote', dest='git_remote_origin', type=str, |
| 425 |
default='origin', metavar='REMOTE', |
| 426 |
help='git remote to push notes to') |
| 427 |
parser.add_argument('--git-refs', dest='dbus_api_git_refs', type=str, |
| 428 |
default='notes/dbus/api', metavar='REF-PATH', |
| 429 |
help='Path beneath refs/ where the git notes will be' |
| 430 |
' stored containing the API signatures database') |
| 431 |
parser.add_argument('--no-push', action='store_const', const=True, |
| 432 |
default=False, |
| 433 |
help='Disable automatic pushing the API signature ' |
| 434 |
'database to a remote repository') |
| 435 |
|
| 436 |
subparsers = parser.add_subparsers() |
| 437 |
|
| 438 |
# dist command |
| 439 |
parser_dist = subparsers.add_parser('dist') |
| 440 |
parser_dist.add_argument('dbus_api_xml_files', metavar='API-FILE', |
| 441 |
type=str, nargs='+', |
| 442 |
help='D-Bus API XML file to check') |
| 443 |
parser_dist.add_argument('--ignore-existing', action='store_const', |
| 444 |
const=True, default=False, |
| 445 |
help='Ignore existing API signatures rather than ' |
| 446 |
'erroring') |
| 447 |
parser_dist.set_defaults(func=command_dist) |
| 448 |
|
| 449 |
# check command |
| 450 |
parser_check = subparsers.add_parser('check') |
| 451 |
parser_check.add_argument('--diff-warnings', dest='warnings', type=str, |
| 452 |
default='all', |
| 453 |
help='Comma-separated list of warnings to ' |
| 454 |
'enable when running dbus-interface-diff') |
| 455 |
parser_check.add_argument('--fatal-warnings', action='store_const', |
| 456 |
const=True, default=False, |
| 457 |
help='Treat all warnings as fatal') |
| 458 |
parser_check.add_argument('old_ref', metavar='OLD-REF', |
| 459 |
type=str, nargs='?', default='', |
| 460 |
help='Old ref to compare; or empty for the ' |
| 461 |
'latest signed tag') |
| 462 |
parser_check.add_argument('new_ref', metavar='NEW-REF', |
| 463 |
type=str, nargs='?', default='', |
| 464 |
help='New ref to compare; or empty for HEAD') |
| 465 |
parser_check.set_defaults(func=command_check) |
| 466 |
|
| 467 |
# install command |
| 468 |
parser_install = subparsers.add_parser('install') |
| 469 |
parser_install.add_argument('dbus_api_xml_files', metavar='API-FILE', |
| 470 |
type=str, nargs='+', |
| 471 |
help='D-Bus API XML file to install') |
| 472 |
parser_install.set_defaults(func=command_install) |
| 473 |
|
| 474 |
args = parser.parse_args() |
| 475 |
|
| 476 |
# Bail early if the .git directory does not exist, since that's our data |
| 477 |
# store. |
| 478 |
git_dir = args.git_dir |
| 479 |
if git_dir == '': |
| 480 |
git_dir = os.path.join(args.git_work_tree, '.git') |
| 481 |
if not os.path.isdir(git_dir): |
| 482 |
sys.stderr.write('error: Could not find git directory ‘%s’. ' |
| 483 |
'Skipping.\n' % git_dir) |
| 484 |
return 0 |
| 485 |
|
| 486 |
return args.func(args) |
| 487 |
|
| 488 |
|
| 489 |
if __name__ == '__main__': |
| 490 |
main() |