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 # Returns a `_CfgCmdCfg` object from the command-line parsing results
 113 # `parse_res`.
 114 def _cfg_cmd_cfg_from_parse_res(parse_res):
 115     # check configuration file path
 116     cfg_file_path = None
 117
 118     for item in parse_res.items:
 119         if type(item) is barectf_argpar._NonOptItem:
 120             if cfg_file_path is not None:
 121                 raise _CliError('Multiple configuration file paths provided')
 122
 123             cfg_file_path = item.text
 124
 125     if cfg_file_path is None:
 126         raise _CliError('Missing configuration file path')
 127
 128     if not os.path.isfile(cfg_file_path):
 129         raise _CliError(f'`{cfg_file_path}` is not an existing, regular file')
 130
 131     # inclusion directories
 132     inclusion_dirs = [item.arg_text for item in _find_opt_items(parse_res.items, 'include-dir')]
 133
 134     for dir in inclusion_dirs:
 135         if not os.path.isdir(dir):
 136             raise _CliError(f'`{dir}` is not an existing directory')
 137
 138     inclusion_dirs.append(os.getcwd())
 139
 140     # other options
 141     ignore_inclusion_file_not_found = _opt_item_val(parse_res.items, 'ignore-include-not-found',
 142                                                     False)
 143
 144     return _CfgCmdCfg(cfg_file_path, inclusion_dirs, ignore_inclusion_file_not_found)
 145
 146
 147 def _print_gen_cmd_usage():
 148     print('''Usage: barectf generate [--code-dir=DIR] [--headers-dir=DIR]
 149                         [--metadata-dir=DIR] [--prefix=PREFIX]
 150                         [--include-dir=DIR]... [--ignore-include-not-found]
 151                         CONFIG-FILE-PATH
 152
 153 Options:
 154   -c DIR, --code-dir=DIR        Write C source files to DIR instead of the CWD
 155   -H DIR, --headers-dir=DIR     Write C header files to DIR instead of the CWD
 156   --ignore-include-not-found    Continue to process the configuration file when
 157                                 included files are not found
 158   -I DIR, --include-dir=DIR     Add DIR to the list of directories to be
 159                                 searched for inclusion files
 160   -m DIR, --metadata-dir=DIR    Write the metadata stream file to DIR instead of
 161                                 the CWD
 162   -p PREFIX, --prefix=PREFIX    Set the configuration prefix to PREFIX''')
 163
 164
 165 # Returns a source and metadata stream file generating command object
 166 # from the specific command-line arguments `orig_args`.
 167 def _gen_cmd_cfg_from_args(orig_args):
 168     # parse original arguments
 169     opt_descrs = [
 170         barectf_argpar.OptDescr('h', 'help'),
 171         barectf_argpar.OptDescr('c', 'code-dir', True),
 172         barectf_argpar.OptDescr('H', 'headers-dir', True),
 173         barectf_argpar.OptDescr('I', 'include-dir', True),
 174         barectf_argpar.OptDescr('m', 'metadata-dir', True),
 175         barectf_argpar.OptDescr('p', 'prefix', True),
 176         barectf_argpar.OptDescr(long_name='dump-config'),
 177         barectf_argpar.OptDescr(long_name='ignore-include-not-found'),
 178     ]
 179     res = barectf_argpar.parse(orig_args, opt_descrs)
 180     assert len(res.ingested_orig_args) == len(orig_args)
 181
 182     # command help?
 183     if len(_find_opt_items(res.items, 'help')) > 0:
 184         _print_gen_cmd_usage()
 185         sys.exit()
 186
 187     # get common configuration file command CLI configuration
 188     cfg_cmd_cfg = _cfg_cmd_cfg_from_parse_res(res)
 189
 190     # directories
 191     c_source_dir = _opt_item_val(res.items, 'code-dir', os.getcwd())
 192     c_header_dir = _opt_item_val(res.items, 'headers-dir', os.getcwd())
 193     metadata_stream_dir = _opt_item_val(res.items, 'metadata-dir', os.getcwd())
 194
 195     for dir in [c_source_dir, c_header_dir, metadata_stream_dir]:
 196         if not os.path.isdir(dir):
 197             raise _CliError(f'`{dir}` is not an existing directory')
 198
 199     # other options
 200     dump_config = _opt_item_val(res.items, 'dump-config', False)
 201     v2_prefix = _opt_item_val(res.items, 'prefix')
 202
 203     return _GenCmd(_GenCmdCfg(cfg_cmd_cfg.cfg_file_path, c_source_dir, c_header_dir,
 204                               metadata_stream_dir, cfg_cmd_cfg.inclusion_dirs,
 205                               cfg_cmd_cfg.ignore_inclusion_file_not_found, dump_config, v2_prefix))
 206
 207
 208 def _print_show_effective_cfg_cmd_usage():
 209     print('''Usage: barectf show-effective-configuration [--include-dir=DIR]...
 210                                             [--ignore-include-not-found]
 211                                             [--indent-spaces=COUNT] CONFIG-FILE-PATH
 212
 213 Options:
 214   --ignore-include-not-found    Continue to process the configuration file when
 215                                 included files are not found
 216   -I DIR, --include-dir=DIR     Add DIR to the list of directories to be
 217                                 searched for inclusion files
 218   --indent-spaces=COUNT         Use COUNT spaces at a time to indent YAML lines
 219                                 instead of 2''')
 220
 221
 222 # Returns an effective configuration showing command object from the
 223 # specific command-line arguments `orig_args`.
 224 def _show_effective_cfg_cfg_from_args(orig_args):
 225     # parse original arguments
 226     opt_descrs = [
 227         barectf_argpar.OptDescr('h', 'help'),
 228         barectf_argpar.OptDescr('I', 'include-dir', True),
 229         barectf_argpar.OptDescr(long_name='indent-spaces', has_arg=True),
 230         barectf_argpar.OptDescr(long_name='ignore-include-not-found'),
 231     ]
 232     res = barectf_argpar.parse(orig_args, opt_descrs)
 233     assert len(res.ingested_orig_args) == len(orig_args)
 234
 235     # command help?
 236     if len(_find_opt_items(res.items, 'help')) > 0:
 237         _print_show_effective_cfg_cmd_usage()
 238         sys.exit()
 239
 240     # get common configuration command CLI configuration
 241     cfg_cmd_cfg = _cfg_cmd_cfg_from_parse_res(res)
 242
 243     # other options
 244     indent_space_count = _opt_item_val(res.items, 'indent-spaces', 2)
 245
 246     try:
 247         indent_space_count = int(indent_space_count)
 248     except (ValueError, TypeError):
 249         raise _CliError(f'Invalid `--indent-spaces` option argument: `{indent_space_count}`')
 250
 251     if indent_space_count < 1 or indent_space_count > 8:
 252         raise _CliError(f'Invalid `--indent-spaces` option argument (`{indent_space_count}`): expecting a value in [1, 8]')
 253
 254     return _ShowEffectiveCfgCmd(_ShowEffectiveCfgCmdCfg(cfg_cmd_cfg.cfg_file_path,
 255                                                         cfg_cmd_cfg.inclusion_dirs,
 256                                                         cfg_cmd_cfg.ignore_inclusion_file_not_found,
 257                                                         indent_space_count))
 258
 259
 260 def _print_general_usage():
 261     print('''Usage: barectf COMMAND COMMAND-ARGS
 262        barectf --help
 263        barectf --version
 264
 265 General options:
 266   -h, --help       Show this help and quit
 267   -V, --version    Show version and quit
 268
 269 Available commands:
 270   gen, generate                   Generate the C source and CTF metadata files
 271                                   of a tracer from a configuration file
 272   show-effective-configuration,   Print the effective configuration file for a
 273   show-effective-config           given configuration file and inclusion
 274                                   directories
 275
 276 Run `barectf COMMAND --help` to show the help of COMMAND.''')
 277
 278
 279 # Returns a command object from the command-line arguments `orig_args`.
 280 #
 281 # All the `orig_args` elements are considered.
 282 def _cmd_from_args(orig_args):
 283     # We use our `argpar` module here instead of Python's `argparse`
 284     # because we need to support the two following use cases:
 285     #
 286     #     $ barectf config.yaml
 287     #     $ barectf generate config.yaml
 288     #
 289     # In other words, the default command is `generate` (for backward
 290     # compatibility reasons). The argument parser must not consider
 291     # `config.yaml` as being a command name.
 292     general_opt_descrs = [
 293         barectf_argpar.OptDescr('V', 'version'),
 294         barectf_argpar.OptDescr('h', 'help'),
 295     ]
 296     res = barectf_argpar.parse(orig_args, general_opt_descrs, False)
 297
 298     # find command name, collecting preceding (common) option items
 299     cmd_from_args_funcs = {
 300         'generate': _gen_cmd_cfg_from_args,
 301         'gen': _gen_cmd_cfg_from_args,
 302         'show-effective-configuration': _show_effective_cfg_cfg_from_args,
 303         'show-effective-config': _show_effective_cfg_cfg_from_args,
 304         'show-effective-cfg': _show_effective_cfg_cfg_from_args,
 305     }
 306     general_opt_items = []
 307     cmd_first_orig_arg_index = None
 308     cmd_from_args_func = None
 309
 310     for item in res.items:
 311         if type(item) is barectf_argpar._NonOptItem:
 312             cmd_from_args_func = cmd_from_args_funcs.get(item.text)
 313
 314             if cmd_from_args_func is None:
 315                 cmd_first_orig_arg_index = item.orig_arg_index
 316             else:
 317                 cmd_first_orig_arg_index = item.orig_arg_index + 1
 318
 319             break
 320         else:
 321             assert type(item) is barectf_argpar._OptItem
 322             general_opt_items.append(item)
 323
 324     # general help?
 325     if len(_find_opt_items(general_opt_items, 'help')) > 0:
 326         _print_general_usage()
 327         sys.exit()
 328
 329     # version?
 330     if len(_find_opt_items(general_opt_items, 'version')) > 0:
 331         print(f'barectf {barectf.__version__}')
 332         sys.exit()
 333
 334     # execute command
 335     cmd_orig_args = orig_args[cmd_first_orig_arg_index:]
 336
 337     if cmd_from_args_func is None:
 338         # default `generate` command
 339         return _gen_cmd_cfg_from_args(cmd_orig_args)
 340     else:
 341         return cmd_from_args_func(cmd_orig_args)
 342
 343
 344 class _CmdCfg:
 345     pass
 346
 347
 348 class _CfgCmdCfg(_CmdCfg):
 349     def __init__(self, cfg_file_path, inclusion_dirs, ignore_inclusion_file_not_found):
 350         self._cfg_file_path = cfg_file_path
 351         self._inclusion_dirs = inclusion_dirs
 352         self._ignore_inclusion_file_not_found = ignore_inclusion_file_not_found
 353
 354     @property
 355     def cfg_file_path(self):
 356         return self._cfg_file_path
 357
 358     @property
 359     def inclusion_dirs(self):
 360         return self._inclusion_dirs
 361
 362     @property
 363     def ignore_inclusion_file_not_found(self):
 364         return self._ignore_inclusion_file_not_found
 365
 366
 367 class _Cmd:
 368     def __init__(self, cfg):
 369         self._cfg = cfg
 370
 371     @property
 372     def cfg(self):
 373         return self._cfg
 374
 375     def exec(self):
 376         raise NotImplementedError
 377
 378
 379 class _GenCmdCfg(_CfgCmdCfg):
 380     def __init__(self, cfg_file_path, c_source_dir, c_header_dir, metadata_stream_dir,
 381                  inclusion_dirs, ignore_inclusion_file_not_found, dump_config, v2_prefix):
 382         super().__init__(cfg_file_path, inclusion_dirs, ignore_inclusion_file_not_found)
 383         self._c_source_dir = c_source_dir
 384         self._c_header_dir = c_header_dir
 385         self._metadata_stream_dir = metadata_stream_dir
 386         self._dump_config = dump_config
 387         self._v2_prefix = v2_prefix
 388
 389     @property
 390     def c_source_dir(self):
 391         return self._c_source_dir
 392
 393     @property
 394     def c_header_dir(self):
 395         return self._c_header_dir
 396
 397     @property
 398     def metadata_stream_dir(self):
 399         return self._metadata_stream_dir
 400
 401     @property
 402     def dump_config(self):
 403         return self._dump_config
 404
 405     @property
 406     def v2_prefix(self):
 407         return self._v2_prefix
 408
 409
 410 # Source and metadata stream file generating command.
 411 class _GenCmd(_Cmd):
 412     def exec(self):
 413         # create configuration
 414         try:
 415             with open(self.cfg.cfg_file_path) as f:
 416                 if self.cfg.dump_config:
 417                     # print effective configuration file
 418                     print(barectf.effective_configuration_file(f, True, self.cfg.inclusion_dirs,
 419                                                                self.cfg.ignore_inclusion_file_not_found))
 420
 421                     # barectf.configuration_from_file() reads the file again
 422                     # below: rewind.
 423                     f.seek(0)
 424
 425                 config = barectf.configuration_from_file(f, True, self.cfg.inclusion_dirs,
 426                                                          self.cfg.ignore_inclusion_file_not_found)
 427         except barectf._ConfigurationParseError as exc:
 428             _print_config_error(exc)
 429         except Exception as exc:
 430             _print_unknown_exc(exc)
 431
 432         if self.cfg.v2_prefix is not None:
 433             # Override prefixes.
 434             #
 435             # For historical reasons, the `--prefix` option applies the
 436             # barectf 2 configuration prefix rules. Therefore, get the
 437             # equivalent barectf 3 prefixes first.
 438             v3_prefixes = barectf_config_parse_common._v3_prefixes_from_v2_prefix(self.cfg.v2_prefix)
 439             cg_opts = config.options.code_generation_options
 440             cg_opts = barectf.ConfigurationCodeGenerationOptions(v3_prefixes.identifier,
 441                                                                  v3_prefixes.file_name,
 442                                                                  cg_opts.default_stream_type,
 443                                                                  cg_opts.header_options,
 444                                                                  cg_opts.clock_type_c_types)
 445             config = barectf.Configuration(config.trace, barectf.ConfigurationOptions(cg_opts))
 446
 447         # create a barectf code generator
 448         code_gen = barectf.CodeGenerator(config)
 449
 450         def write_file(dir, file):
 451             with open(os.path.join(dir, file.name), 'w') as f:
 452                 f.write(file.contents)
 453
 454         def write_files(dir, files):
 455             for file in files:
 456                 write_file(dir, file)
 457
 458         try:
 459             # generate and write metadata stream file
 460             write_file(self.cfg.metadata_stream_dir, code_gen.generate_metadata_stream())
 461
 462             # generate and write C header files
 463             write_files(self.cfg.c_header_dir, code_gen.generate_c_headers())
 464
 465             # generate and write C source files
 466             write_files(self.cfg.c_source_dir, code_gen.generate_c_sources())
 467         except Exception as exc:
 468             # We know `config` is valid, therefore the code generator cannot
 469             # fail for a reason known to barectf.
 470             _print_unknown_exc(exc)
 471
 472
 473 class _ShowEffectiveCfgCmdCfg(_CfgCmdCfg):
 474     def __init__(self, cfg_file_path, inclusion_dirs, ignore_inclusion_file_not_found,
 475                  indent_space_count):
 476         super().__init__(cfg_file_path, inclusion_dirs, ignore_inclusion_file_not_found)
 477         self._indent_space_count = indent_space_count
 478
 479     @property
 480     def indent_space_count(self):
 481         return self._indent_space_count
 482
 483
 484 # Effective configuration showing command.
 485 class _ShowEffectiveCfgCmd(_Cmd):
 486     def exec(self):
 487         try:
 488             with open(self.cfg.cfg_file_path) as f:
 489                 print(barectf.effective_configuration_file(f, True, self.cfg.inclusion_dirs,
 490                                                            self.cfg.ignore_inclusion_file_not_found,
 491                                                            self.cfg.indent_space_count))
 492         except barectf._ConfigurationParseError as exc:
 493             _print_config_error(exc)
 494         except Exception as exc:
 495             _print_unknown_exc(exc)
 496
 497
 498 def _run():
 499     # create command from arguments
 500     try:
 501         cmd = _cmd_from_args(sys.argv[1:])
 502     except barectf_argpar._Error as exc:
 503         _print_error(f'Command-line: For argument `{exc.orig_arg}`: {exc.msg}')
 504     except _CliError as exc:
 505         _print_error(f'Command-line: {exc}')
 506
 507     # execute command
 508     cmd.exec()