barectf/cli.py

   1 # The MIT License (MIT)
   2 #
   3 # Copyright (c) 2014-2020 Philippe Proulx <pproulx@efficios.com>
   4 #
   5 # Permission is hereby granted, free of charge, to any person obtaining
   6 # a copy of this software and associated documentation files (the
   7 # "Software"), to deal in the Software without restriction, including
   8 # without limitation the rights to use, copy, modify, merge, publish,
   9 # distribute, sublicense, and/or sell copies of the Software, and to
  10 # permit persons to whom the Software is furnished to do so, subject to
  11 # the following conditions:
  12 #
  13 # The above copyright notice and this permission notice shall be
  14 # included in all copies or substantial portions of the Software.
  15 #
  16 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  17 # EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  18 # MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  19 # IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
  20 # CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
  21 # TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  22 # SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  23
  24 import pkg_resources
  25 import collections
  26 import termcolor
  27 import argparse
  28 import os.path
  29 import barectf
  30 import barectf.config_parse_common as barectf_config_parse_common
  31 import barectf.argpar as barectf_argpar
  32 import sys
  33 import os
  34
  35
  36 # Colors and prints the error message `msg` and exits with status code
  37 # 1.
  38 def _print_error(msg):
  39     termcolor.cprint('Error: ', 'red', end='', file=sys.stderr)
  40     termcolor.cprint(msg, 'red', attrs=['bold'], file=sys.stderr)
  41     sys.exit(1)
  42
  43
  44 # Pretty-prints the barectf configuration error `exc` and exits with
  45 # status code 1.
  46 def _print_config_error(exc):
  47     # reverse: most precise message comes last
  48     for ctx in reversed(exc.context):
  49         msg = ''
  50
  51         if ctx.message is not None:
  52             msg = f' {ctx.message}'
  53
  54         color = 'red'
  55         termcolor.cprint(f'{ctx.name}', color, attrs=['bold'], file=sys.stderr, end='')
  56         termcolor.cprint(':', color, file=sys.stderr, end='')
  57         termcolor.cprint(msg, color, file=sys.stderr)
  58
  59     sys.exit(1)
  60
  61
  62 # Pretty-prints the unknown exception `exc`.
  63 def _print_unknown_exc(exc):
  64     import traceback
  65
  66     traceback.print_exc()
  67     _print_error(f'Unknown exception: {exc}')
  68
  69
  70 # Finds and returns all the option items in `items` having the long name
  71 # `long_name`.
  72 def _find_opt_items(items, long_name):
  73     ret_items = []
  74
  75     for item in items:
  76         if type(item) is barectf_argpar._OptItem and item.descr.long_name == long_name:
  77             ret_items.append(item)
  78
  79     return ret_items
  80
  81
  82 # Returns:
  83 #
  84 # For an option item without an argument:
  85 #     `True`.
  86 #
  87 # For an option item with an argument:
  88 #     Its argument.
  89 #
  90 # Uses the last option item having the long name `long_name` found in
  91 # `items`.
  92 #
  93 # Returns `default` if there's no such option item.
  94 def _opt_item_val(items, long_name, default=None):
  95     opt_items = _find_opt_items(items, long_name)
  96
  97     if len(opt_items) == 0:
  98         return default
  99
 100     opt_item = opt_items[-1]
 101
 102     if opt_item.descr.has_arg:
 103         return opt_item.arg_text
 104
 105     return True
 106
 107
 108 class _CliError(Exception):
 109     pass
 110
 111
 112 def _cfg_file_path_from_parse_res(parse_res):
 113     cfg_file_path = None
 114
 115     for item in parse_res.items:
 116         if type(item) is barectf_argpar._NonOptItem:
 117             if cfg_file_path is not None:
 118                 raise _CliError('Multiple configuration file paths provided')
 119
 120             cfg_file_path = item.text
 121
 122     if cfg_file_path is None:
 123         raise _CliError('Missing configuration file path')
 124
 125     if not os.path.isfile(cfg_file_path):
 126         raise _CliError(f'`{cfg_file_path}` is not an existing, regular file')
 127
 128     return cfg_file_path
 129
 130
 131 # Returns a `_CfgCmdCfg` object from the command-line parsing results
 132 # `parse_res`.
 133 def _cfg_cmd_cfg_from_parse_res(parse_res):
 134     # check configuration file path
 135     cfg_file_path = _cfg_file_path_from_parse_res(parse_res)
 136
 137     # inclusion directories
 138     inclusion_dirs = [item.arg_text for item in _find_opt_items(parse_res.items, 'include-dir')]
 139
 140     for dir in inclusion_dirs:
 141         if not os.path.isdir(dir):
 142             raise _CliError(f'`{dir}` is not an existing directory')
 143
 144     inclusion_dirs.append(os.getcwd())
 145
 146     # other options
 147     ignore_inclusion_file_not_found = _opt_item_val(parse_res.items, 'ignore-include-not-found',
 148                                                     False)
 149
 150     return _CfgCmdCfg(cfg_file_path, inclusion_dirs, ignore_inclusion_file_not_found)
 151
 152
 153 def _print_gen_cmd_usage():
 154     print('''Usage: barectf generate [--code-dir=DIR] [--headers-dir=DIR]
 155                         [--metadata-dir=DIR] [--prefix=PREFIX]
 156                         [--include-dir=DIR]... [--ignore-include-not-found]
 157                         CONFIG-FILE-PATH
 158        barectf generate --help
 159
 160 Options:
 161   -c DIR, --code-dir=DIR        Write C source files to DIR instead of the CWD
 162   -H DIR, --headers-dir=DIR     Write C header files to DIR instead of the CWD
 163   -h, --help                    Show this help and quit
 164   --ignore-include-not-found    Continue to process the configuration file when
 165                                 included files are not found
 166   -I DIR, --include-dir=DIR     Add DIR to the list of directories to be
 167                                 searched for inclusion files
 168   -m DIR, --metadata-dir=DIR    Write the metadata stream file to DIR instead of
 169                                 the CWD
 170   -p PREFIX, --prefix=PREFIX    Set the configuration prefix to PREFIX''')
 171
 172
 173 # Returns a source and metadata stream file generating command object
 174 # from the specific command-line arguments `orig_args`.
 175 def _gen_cmd_cfg_from_args(orig_args):
 176     # parse original arguments
 177     opt_descrs = [
 178         barectf_argpar.OptDescr('h', 'help'),
 179         barectf_argpar.OptDescr('c', 'code-dir', True),
 180         barectf_argpar.OptDescr('H', 'headers-dir', True),
 181         barectf_argpar.OptDescr('I', 'include-dir', True),
 182         barectf_argpar.OptDescr('m', 'metadata-dir', True),
 183         barectf_argpar.OptDescr('p', 'prefix', True),
 184         barectf_argpar.OptDescr(long_name='dump-config'),
 185         barectf_argpar.OptDescr(long_name='ignore-include-not-found'),
 186     ]
 187     res = barectf_argpar.parse(orig_args, opt_descrs)
 188     assert len(res.ingested_orig_args) == len(orig_args)
 189
 190     # command help?
 191     if len(_find_opt_items(res.items, 'help')) > 0:
 192         _print_gen_cmd_usage()
 193         sys.exit()
 194
 195     # get common configuration file command CLI configuration
 196     cfg_cmd_cfg = _cfg_cmd_cfg_from_parse_res(res)
 197
 198     # directories
 199     c_source_dir = _opt_item_val(res.items, 'code-dir', os.getcwd())
 200     c_header_dir = _opt_item_val(res.items, 'headers-dir', os.getcwd())
 201     metadata_stream_dir = _opt_item_val(res.items, 'metadata-dir', os.getcwd())
 202
 203     for dir in [c_source_dir, c_header_dir, metadata_stream_dir]:
 204         if not os.path.isdir(dir):
 205             raise _CliError(f'`{dir}` is not an existing directory')
 206
 207     # other options
 208     dump_config = _opt_item_val(res.items, 'dump-config', False)
 209     v2_prefix = _opt_item_val(res.items, 'prefix')
 210
 211     return _GenCmd(_GenCmdCfg(cfg_cmd_cfg.cfg_file_path, c_source_dir, c_header_dir,
 212                               metadata_stream_dir, cfg_cmd_cfg.inclusion_dirs,
 213                               cfg_cmd_cfg.ignore_inclusion_file_not_found, dump_config, v2_prefix))
 214
 215
 216 def _show_effective_cfg_cmd_usage():
 217     print('''Usage: barectf show-effective-configuration [--include-dir=DIR]...
 218                                             [--ignore-include-not-found]
 219                                             [--indent-spaces=COUNT] CONFIG-FILE-PATH
 220        barectf show-effective-configuration --help
 221
 222 Options:
 223   -h, --help                    Show this help and quit
 224   --ignore-include-not-found    Continue to process the configuration file when
 225                                 included files are not found
 226   -I DIR, --include-dir=DIR     Add DIR to the list of directories to be
 227                                 searched for inclusion files
 228   --indent-spaces=COUNT         Use COUNT spaces at a time to indent YAML lines
 229                                 instead of 2''')
 230
 231
 232 # Returns an effective configuration showing command object from the
 233 # specific command-line arguments `orig_args`.
 234 def _show_effective_cfg_cfg_from_args(orig_args):
 235     # parse original arguments
 236     opt_descrs = [
 237         barectf_argpar.OptDescr('h', 'help'),
 238         barectf_argpar.OptDescr('I', 'include-dir', True),
 239         barectf_argpar.OptDescr(long_name='indent-spaces', has_arg=True),
 240         barectf_argpar.OptDescr(long_name='ignore-include-not-found'),
 241     ]
 242     res = barectf_argpar.parse(orig_args, opt_descrs)
 243     assert len(res.ingested_orig_args) == len(orig_args)
 244
 245     # command help?
 246     if len(_find_opt_items(res.items, 'help')) > 0:
 247         _show_effective_cfg_cmd_usage()
 248         sys.exit()
 249
 250     # get common configuration command CLI configuration
 251     cfg_cmd_cfg = _cfg_cmd_cfg_from_parse_res(res)
 252
 253     # other options
 254     indent_space_count = _opt_item_val(res.items, 'indent-spaces', 2)
 255
 256     try:
 257         indent_space_count = int(indent_space_count)
 258     except (ValueError, TypeError):
 259         raise _CliError(f'Invalid `--indent-spaces` option argument: `{indent_space_count}`')
 260
 261     if indent_space_count < 1 or indent_space_count > 8:
 262         raise _CliError(f'Invalid `--indent-spaces` option argument (`{indent_space_count}`): expecting a value in [1, 8]')
 263
 264     return _ShowEffectiveCfgCmd(_ShowEffectiveCfgCmdCfg(cfg_cmd_cfg.cfg_file_path,
 265                                                         cfg_cmd_cfg.inclusion_dirs,
 266                                                         cfg_cmd_cfg.ignore_inclusion_file_not_found,
 267                                                         indent_space_count))
 268
 269
 270 def _show_cfg_version_cmd_usage():
 271     print('''Usage: barectf show-configuration-version CONFIG-FILE-PATH
 272        barectf show-configuration-version --help
 273
 274 Options:
 275   -h, --help    Show this help and quit''')
 276
 277
 278 # Returns a configuration version showing command object from the
 279 # specific command-line arguments `orig_args`.
 280 def _show_cfg_version_cfg_from_args(orig_args):
 281     # parse original arguments
 282     opt_descrs = [
 283         barectf_argpar.OptDescr('h', 'help'),
 284     ]
 285     res = barectf_argpar.parse(orig_args, opt_descrs)
 286     assert len(res.ingested_orig_args) == len(orig_args)
 287
 288     # command help?
 289     if len(_find_opt_items(res.items, 'help')) > 0:
 290         _show_cfg_version_cmd_usage()
 291         sys.exit()
 292
 293     # check configuration file path
 294     cfg_file_path = _cfg_file_path_from_parse_res(res)
 295
 296     return _ShowCfgVersionCmd(_ShowCfgVersionCmdCfg(cfg_file_path))
 297
 298
 299 def _print_general_usage():
 300     print('''Usage: barectf COMMAND COMMAND-ARGS
 301        barectf --help
 302        barectf --version
 303
 304 General options:
 305   -h, --help       Show this help and quit
 306   -V, --version    Show version and quit
 307
 308 Available commands:
 309   gen:
 310   generate:
 311     Generate the C source and CTF metadata files of a tracer from a
 312     configuration file.
 313
 314   show-effective-configuration:
 315   show-effective-config:
 316   show-effective-cfg:
 317     Print the effective configuration file for a given configuration
 318     file and inclusion directories.
 319
 320   show-configuration-version:
 321   show-config-version:
 322   show-cfg-version
 323     Print the major version of a given configuration file.
 324
 325 Run `barectf COMMAND --help` to show the help of COMMAND.''')
 326
 327
 328 # Returns a command object from the command-line arguments `orig_args`.
 329 #
 330 # All the `orig_args` elements are considered.
 331 def _cmd_from_args(orig_args):
 332     # We use our `argpar` module here instead of Python's `argparse`
 333     # because we need to support the two following use cases:
 334     #
 335     #     $ barectf config.yaml
 336     #     $ barectf generate config.yaml
 337     #
 338     # In other words, the default command is `generate` (for backward
 339     # compatibility reasons). The argument parser must not consider
 340     # `config.yaml` as being a command name.
 341     general_opt_descrs = [
 342         barectf_argpar.OptDescr('V', 'version'),
 343         barectf_argpar.OptDescr('h', 'help'),
 344     ]
 345     res = barectf_argpar.parse(orig_args, general_opt_descrs, False)
 346
 347     # find command name, collecting preceding (common) option items
 348     cmd_from_args_funcs = {
 349         'generate': _gen_cmd_cfg_from_args,
 350         'gen': _gen_cmd_cfg_from_args,
 351         'show-effective-configuration': _show_effective_cfg_cfg_from_args,
 352         'show-effective-config': _show_effective_cfg_cfg_from_args,
 353         'show-effective-cfg': _show_effective_cfg_cfg_from_args,
 354         'show-configuration-version': _show_cfg_version_cfg_from_args,
 355         'show-config-version': _show_cfg_version_cfg_from_args,
 356         'show-cfg-version': _show_cfg_version_cfg_from_args,
 357     }
 358     general_opt_items = []
 359     cmd_first_orig_arg_index = None
 360     cmd_from_args_func = None
 361
 362     for item in res.items:
 363         if type(item) is barectf_argpar._NonOptItem:
 364             cmd_from_args_func = cmd_from_args_funcs.get(item.text)
 365
 366             if cmd_from_args_func is None:
 367                 cmd_first_orig_arg_index = item.orig_arg_index
 368             else:
 369                 cmd_first_orig_arg_index = item.orig_arg_index + 1
 370
 371             break
 372         else:
 373             assert type(item) is barectf_argpar._OptItem
 374             general_opt_items.append(item)
 375
 376     # general help?
 377     if len(_find_opt_items(general_opt_items, 'help')) > 0:
 378         _print_general_usage()
 379         sys.exit()
 380
 381     # version?
 382     if len(_find_opt_items(general_opt_items, 'version')) > 0:
 383         print(f'barectf {barectf.__version__}')
 384         sys.exit()
 385
 386     # execute command
 387     cmd_orig_args = orig_args[cmd_first_orig_arg_index:]
 388
 389     if cmd_from_args_func is None:
 390         # default `generate` command
 391         return _gen_cmd_cfg_from_args(cmd_orig_args)
 392     else:
 393         return cmd_from_args_func(cmd_orig_args)
 394
 395
 396 class _CmdCfg:
 397     pass
 398
 399
 400 class _CfgCmdCfg(_CmdCfg):
 401     def __init__(self, cfg_file_path, inclusion_dirs, ignore_inclusion_file_not_found):
 402         self._cfg_file_path = cfg_file_path
 403         self._inclusion_dirs = inclusion_dirs
 404         self._ignore_inclusion_file_not_found = ignore_inclusion_file_not_found
 405
 406     @property
 407     def cfg_file_path(self):
 408         return self._cfg_file_path
 409
 410     @property
 411     def inclusion_dirs(self):
 412         return self._inclusion_dirs
 413
 414     @property
 415     def ignore_inclusion_file_not_found(self):
 416         return self._ignore_inclusion_file_not_found
 417
 418
 419 class _Cmd:
 420     def __init__(self, cfg):
 421         self._cfg = cfg
 422
 423     @property
 424     def cfg(self):
 425         return self._cfg
 426
 427     def exec(self):
 428         raise NotImplementedError
 429
 430
 431 class _GenCmdCfg(_CfgCmdCfg):
 432     def __init__(self, cfg_file_path, c_source_dir, c_header_dir, metadata_stream_dir,
 433                  inclusion_dirs, ignore_inclusion_file_not_found, dump_config, v2_prefix):
 434         super().__init__(cfg_file_path, inclusion_dirs, ignore_inclusion_file_not_found)
 435         self._c_source_dir = c_source_dir
 436         self._c_header_dir = c_header_dir
 437         self._metadata_stream_dir = metadata_stream_dir
 438         self._dump_config = dump_config
 439         self._v2_prefix = v2_prefix
 440
 441     @property
 442     def c_source_dir(self):
 443         return self._c_source_dir
 444
 445     @property
 446     def c_header_dir(self):
 447         return self._c_header_dir
 448
 449     @property
 450     def metadata_stream_dir(self):
 451         return self._metadata_stream_dir
 452
 453     @property
 454     def dump_config(self):
 455         return self._dump_config
 456
 457     @property
 458     def v2_prefix(self):
 459         return self._v2_prefix
 460
 461
 462 # Source and metadata stream file generating command.
 463 class _GenCmd(_Cmd):
 464     def exec(self):
 465         # create configuration
 466         try:
 467             with open(self.cfg.cfg_file_path) as f:
 468                 if self.cfg.dump_config:
 469                     # print effective configuration file
 470                     print(barectf.effective_configuration_file(f, True, self.cfg.inclusion_dirs,
 471                                                                self.cfg.ignore_inclusion_file_not_found))
 472
 473                     # barectf.configuration_from_file() reads the file again
 474                     # below: rewind.
 475                     f.seek(0)
 476
 477                 config = barectf.configuration_from_file(f, True, self.cfg.inclusion_dirs,
 478                                                          self.cfg.ignore_inclusion_file_not_found)
 479         except barectf._ConfigurationParseError as exc:
 480             _print_config_error(exc)
 481         except Exception as exc:
 482             _print_unknown_exc(exc)
 483
 484         if self.cfg.v2_prefix is not None:
 485             # Override prefixes.
 486             #
 487             # For historical reasons, the `--prefix` option applies the
 488             # barectf 2 configuration prefix rules. Therefore, get the
 489             # equivalent barectf 3 prefixes first.
 490             v3_prefixes = barectf_config_parse_common._v3_prefixes_from_v2_prefix(self.cfg.v2_prefix)
 491             cg_opts = config.options.code_generation_options
 492             cg_opts = barectf.ConfigurationCodeGenerationOptions(v3_prefixes.identifier,
 493                                                                  v3_prefixes.file_name,
 494                                                                  cg_opts.default_stream_type,
 495                                                                  cg_opts.header_options,
 496                                                                  cg_opts.clock_type_c_types)
 497             config = barectf.Configuration(config.trace, barectf.ConfigurationOptions(cg_opts))
 498
 499         # create a barectf code generator
 500         code_gen = barectf.CodeGenerator(config)
 501
 502         def write_file(dir, file):
 503             with open(os.path.join(dir, file.name), 'w') as f:
 504                 f.write(file.contents)
 505
 506         def write_files(dir, files):
 507             for file in files:
 508                 write_file(dir, file)
 509
 510         try:
 511             # generate and write metadata stream file
 512             write_file(self.cfg.metadata_stream_dir, code_gen.generate_metadata_stream())
 513
 514             # generate and write C header files
 515             write_files(self.cfg.c_header_dir, code_gen.generate_c_headers())
 516
 517             # generate and write C source files
 518             write_files(self.cfg.c_source_dir, code_gen.generate_c_sources())
 519         except Exception as exc:
 520             # We know `config` is valid, therefore the code generator cannot
 521             # fail for a reason known to barectf.
 522             _print_unknown_exc(exc)
 523
 524
 525 class _ShowEffectiveCfgCmdCfg(_CfgCmdCfg):
 526     def __init__(self, cfg_file_path, inclusion_dirs, ignore_inclusion_file_not_found,
 527                  indent_space_count):
 528         super().__init__(cfg_file_path, inclusion_dirs, ignore_inclusion_file_not_found)
 529         self._indent_space_count = indent_space_count
 530
 531     @property
 532     def indent_space_count(self):
 533         return self._indent_space_count
 534
 535
 536 # Effective configuration showing command.
 537 class _ShowEffectiveCfgCmd(_Cmd):
 538     def exec(self):
 539         try:
 540             with open(self.cfg.cfg_file_path) as f:
 541                 print(barectf.effective_configuration_file(f, True, self.cfg.inclusion_dirs,
 542                                                            self.cfg.ignore_inclusion_file_not_found,
 543                                                            self.cfg.indent_space_count))
 544         except barectf._ConfigurationParseError as exc:
 545             _print_config_error(exc)
 546         except Exception as exc:
 547             _print_unknown_exc(exc)
 548
 549
 550 class _ShowCfgVersionCmdCfg(_CmdCfg):
 551     def __init__(self, cfg_file_path):
 552         self._cfg_file_path = cfg_file_path
 553
 554     @property
 555     def cfg_file_path(self):
 556         return self._cfg_file_path
 557
 558
 559 class _ShowCfgVersionCmd(_Cmd):
 560     def exec(self):
 561         try:
 562             with open(self.cfg.cfg_file_path) as f:
 563                 print(barectf.configuration_file_major_version(f))
 564         except barectf._ConfigurationParseError as exc:
 565             _print_config_error(exc)
 566         except Exception as exc:
 567             _print_unknown_exc(exc)
 568
 569
 570 def _run():
 571     # create command from arguments
 572     try:
 573         cmd = _cmd_from_args(sys.argv[1:])
 574     except barectf_argpar._Error as exc:
 575         _print_error(f'Command-line: For argument `{exc.orig_arg}`: {exc.msg}')
 576     except _CliError as exc:
 577         _print_error(f'Command-line: {exc}')
 578
 579     # execute command
 580     cmd.exec()