| # Copyright (c) 2017 Open Source Foundries Limited. |
| # |
| # SPDX-License-Identifier: Apache-2.0 |
| |
| '''Sphinx extensions related to managing Zephyr applications.''' |
| |
| from docutils import nodes |
| from docutils.parsers.rst import Directive |
| from docutils.parsers.rst import directives |
| |
| |
| # TODO: extend and modify this for Windows. |
| # |
| # This could be as simple as generating a couple of sets of instructions, one |
| # for Unix environments, and another for Windows. |
| class ZephyrAppCommandsDirective(Directive): |
| '''Zephyr directive for generating documentation with the shell |
| commands needed to manage (build, flash, etc.) an application. |
| |
| For example, to generate commands to build samples/hello_world for |
| qemu_x86: |
| |
| .. zephyr-app-commands:: |
| :zephyr-app: samples/hello_world |
| :board: qemu_x86 |
| :goals: build |
| |
| Directive options: |
| |
| - :app: if set, the commands will change directories to this path to the |
| application. |
| |
| - :zephyr-app: like :app:, but includes instructions from the Zephyr base |
| directory. Cannot be given with :app:. |
| |
| - :generator: which build system to generate. Valid options are |
| currently 'ninja' and 'make'. The default is 'make'. This option |
| is not case sensitive. |
| |
| - :board: if set, the application build will target the given board. |
| |
| - :conf: if set, the application build will use the given configuration |
| file. |
| |
| - :gen-args: if set, additional arguments to the CMake invocation |
| |
| - :build-args: if set, additional arguments to the build invocation |
| |
| - :build-dir: if set, the application build directory will *APPEND* this |
| (relative, Unix-separated) path to the standard build directory. This is |
| mostly useful for distinguishing builds for one application within a |
| single page. |
| |
| - :goals: a whitespace-separated list of what to do with the app (in |
| 'build', 'flash', 'debug', 'debugserver', 'run'). Commands to accomplish |
| these tasks will be generated in the right order. |
| |
| - :maybe-skip-config: if set, this indicates the reader may have already |
| created a build directory and changed there, and will tweak the text to |
| note that doing so again is not necessary. |
| |
| - :compact: if set, the generated output is a single code block with no |
| additional comment lines |
| |
| ''' |
| has_content = False |
| required_arguments = 0 |
| optional_arguments = 0 |
| final_argument_whitespace = False |
| option_spec = { |
| 'app': directives.unchanged, |
| 'zephyr-app': directives.unchanged, |
| 'generator': directives.unchanged, |
| 'board': directives.unchanged, |
| 'conf': directives.unchanged, |
| 'gen-args': directives.unchanged, |
| 'build-args': directives.unchanged, |
| 'build-dir': directives.unchanged, |
| 'goals': directives.unchanged_required, |
| 'maybe-skip-config': directives.flag, |
| 'compact': directives.flag |
| } |
| |
| GENERATORS = ['make', 'ninja'] |
| |
| def run(self): |
| # Re-run on the current document if this directive's source changes. |
| self.state.document.settings.env.note_dependency(__file__) |
| |
| # Parse directive options. Don't use os.path.sep or os.path.join here! |
| # That would break if building the docs on Windows. |
| app = self.options.get('app', None) |
| zephyr_app = self.options.get('zephyr-app', None) |
| generator = self.options.get('generator', 'make').lower() |
| board = self.options.get('board', None) |
| conf = self.options.get('conf', None) |
| gen_args = self.options.get('gen-args', None) |
| build_args = self.options.get('build-args', None) |
| build_dir_append = self.options.get('build-dir', '').strip('/') |
| goals = self.options.get('goals').split() |
| skip_config = 'maybe-skip-config' in self.options |
| compact = 'compact' in self.options |
| |
| if app and zephyr_app: |
| raise self.error('Both app and zephyr-app options were given.') |
| |
| if generator not in self.GENERATORS: |
| raise self.error('Unknown generator {}; choose from: {}'.format( |
| generator, self.GENERATORS)) |
| |
| if compact and skip_config: |
| raise self.error('Both compact and maybe-skip-config options were given.') |
| |
| # Allow build directories which are nested. |
| build_dir = ('build' + '/' + build_dir_append).rstrip('/') |
| num_slashes = build_dir.count('/') |
| source_dir = '/'.join(['..' for i in range(num_slashes + 1)]) |
| mkdir = 'mkdir' if num_slashes == 0 else 'mkdir -p' |
| |
| run_config = { |
| 'board': board, |
| 'conf': conf, |
| 'gen_args': gen_args, |
| 'build_args': build_args, |
| 'source_dir': source_dir, |
| 'goals': goals, |
| 'compact': compact |
| } |
| |
| # Build the command content as a list, then convert to string. |
| content = [] |
| |
| if zephyr_app: |
| content.append('$ cd $ZEPHYR_BASE/{}'.format(zephyr_app)) |
| if not compact: |
| content.append('') |
| elif app: |
| content.append('$ cd {}'.format(app)) |
| if not compact: |
| content.append('') |
| |
| if skip_config: |
| content.append("# If you already made a build directory ({}) and ran cmake, just 'cd {}' instead.".format(build_dir, build_dir)) # noqa: E501 |
| elif not compact: |
| content.append('# Make a build directory, and use cmake to configure a {}-based build system:'.format(generator.capitalize())) # noqa: E501 |
| content.append('$ {} {} && cd {}'.format(mkdir, build_dir, build_dir)) |
| |
| if generator == 'make': |
| content.extend(self._generate_make(**run_config)) |
| elif generator == 'ninja': |
| content.extend(self._generate_ninja(**run_config)) |
| |
| content = '\n'.join(content) |
| |
| # Create the nodes. |
| literal = nodes.literal_block(content, content) |
| self.add_name(literal) |
| literal['language'] = 'console' |
| return [literal] |
| |
| def _generate_make(self, **kwargs): |
| board = kwargs['board'] |
| conf = kwargs['conf'] |
| gen_args = kwargs['gen_args'] |
| build_args = kwargs['build_args'] |
| source_dir = kwargs['source_dir'] |
| goals = kwargs['goals'] |
| compact = kwargs['compact'] |
| |
| board_arg = ' -DBOARD={}'.format(board) if board else '' |
| conf_arg = ' -DCONF_FILE={}'.format(conf) if conf else '' |
| gen_args = ' {}'.format(gen_args) if gen_args else '' |
| build_args = ' {}'.format(build_args) if build_args else '' |
| |
| content = [] |
| content.extend([ |
| '$ cmake{}{}{} {}'.format(board_arg, conf_arg, gen_args, |
| source_dir)]) |
| if not compact: |
| content.extend(['', |
| '# Now run make on the generated build system:']) |
| if 'build' in goals: |
| content.append('$ make{}'.format(build_args)) |
| for goal in goals: |
| if goal == 'build': |
| continue |
| content.append('$ make {}'.format(goal)) |
| return content |
| |
| def _generate_ninja(self, **kwargs): |
| board = kwargs['board'] |
| conf = kwargs['conf'] |
| gen_args = kwargs['gen_args'] |
| build_args = kwargs['build_args'] |
| source_dir = kwargs['source_dir'] |
| goals = kwargs['goals'] |
| compact = kwargs['compact'] |
| |
| board_arg = ' -DBOARD={}'.format(board) if board else '' |
| conf_arg = ' -DCONF_FILE={}'.format(conf) if conf else '' |
| gen_args = ' {}'.format(gen_args) if gen_args else '' |
| build_args = ' {}'.format(build_args) if build_args else '' |
| |
| content = [] |
| content.extend([ |
| '$ cmake -GNinja{}{}{} {}'.format(board_arg, conf_arg, gen_args, |
| source_dir)]) |
| if not compact: |
| content.extend(['', |
| '# Now run ninja on the generated build system:']) |
| if 'build' in goals: |
| content.append('$ ninja{}'.format(build_args)) |
| for goal in goals: |
| if goal == 'build': |
| continue |
| content.append('$ ninja {}'.format(goal)) |
| return content |
| |
| |
| def setup(app): |
| app.add_directive('zephyr-app-commands', ZephyrAppCommandsDirective) |
| |
| return { |
| 'version': '1.0', |
| 'parallel_read_safe': True, |
| 'parallel_write_safe': True |
| } |
