doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
# 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):
|
2019-03-21 21:38:03 +01:00
|
|
|
r'''
|
2018-05-05 01:31:05 +02:00
|
|
|
This is a Zephyr directive for generating consistent documentation
|
|
|
|
of the shell commands needed to manage (build, flash, etc.) an application.
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
|
|
|
|
For example, to generate commands to build samples/hello_world for
|
2018-05-05 01:31:05 +02:00
|
|
|
qemu_x86 use::
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
|
2018-05-05 01:31:05 +02:00
|
|
|
.. zephyr-app-commands::
|
|
|
|
:zephyr-app: samples/hello_world
|
|
|
|
:board: qemu_x86
|
|
|
|
:goals: build
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
|
|
|
|
Directive options:
|
|
|
|
|
2019-02-10 13:51:16 +01:00
|
|
|
\:tool:
|
|
|
|
which tool to use. Valid options are currently 'cmake', 'west' and 'all'.
|
2019-08-25 19:06:22 +02:00
|
|
|
The default is 'west'.
|
2019-02-10 13:51:16 +01:00
|
|
|
|
2018-05-05 01:31:05 +02:00
|
|
|
\:app:
|
2019-06-13 14:55:08 +02:00
|
|
|
path to the application to build.
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
|
2018-05-05 01:31:05 +02:00
|
|
|
\:zephyr-app:
|
2019-06-13 14:55:08 +02:00
|
|
|
path to the application to build, this is an app present in the upstream
|
|
|
|
zephyr repository. Mutually exclusive with \:app:.
|
|
|
|
|
|
|
|
\:cd-into:
|
|
|
|
if set, build instructions are given from within the \:app: folder,
|
|
|
|
instead of outside of it.
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
|
2018-05-05 01:31:05 +02:00
|
|
|
\:generator:
|
|
|
|
which build system to generate. Valid options are
|
2018-01-17 18:29:01 +01:00
|
|
|
currently 'ninja' and 'make'. The default is 'ninja'. This option
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
is not case sensitive.
|
|
|
|
|
2018-05-05 01:31:05 +02:00
|
|
|
\:host-os:
|
|
|
|
which host OS the instructions are for. Valid options are
|
|
|
|
'unix', 'win' and 'all'. The default is 'all'.
|
2018-01-17 18:29:01 +01:00
|
|
|
|
2018-05-05 01:31:05 +02:00
|
|
|
\:board:
|
|
|
|
if set, the application build will target the given board.
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
|
2019-01-18 19:09:27 +01:00
|
|
|
\:shield:
|
|
|
|
if set, the application build will target the given shield.
|
|
|
|
|
2018-05-05 01:31:05 +02:00
|
|
|
\:conf:
|
|
|
|
if set, the application build will use the given configuration
|
|
|
|
file. If multiple conf files are provided, enclose the
|
|
|
|
space-separated list of files with quotes, e.g., "a.conf b.conf".
|
2017-11-10 11:42:47 +01:00
|
|
|
|
2018-05-05 01:31:05 +02:00
|
|
|
\:gen-args:
|
|
|
|
if set, additional arguments to the CMake invocation
|
2017-11-10 11:42:47 +01:00
|
|
|
|
2018-05-05 01:31:05 +02:00
|
|
|
\:build-args:
|
|
|
|
if set, additional arguments to the build invocation
|
2017-11-10 11:42:47 +01:00
|
|
|
|
2023-12-03 12:43:29 +01:00
|
|
|
\:snippets:
|
|
|
|
if set, indicates the application should be compiled with the listed snippets.
|
|
|
|
Multiple snippets can be provided in a comma separated list.
|
|
|
|
|
2018-05-05 01:31:05 +02:00
|
|
|
\:build-dir:
|
|
|
|
if set, the application build directory will *APPEND* this
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
(relative, Unix-separated) path to the standard build directory. This is
|
|
|
|
mostly useful for distinguishing builds for one application within a
|
|
|
|
single page.
|
|
|
|
|
2023-12-01 07:45:12 +01:00
|
|
|
\:build-dir-fmt:
|
|
|
|
if set, assume that "west config build.dir-fmt" has been set to this
|
|
|
|
path. Exclusive with 'build-dir' and depends on 'tool=west'.
|
|
|
|
|
2018-05-05 01:31:05 +02:00
|
|
|
\:goals:
|
|
|
|
a whitespace-separated list of what to do with the app (in
|
2017-11-10 13:22:41 +01:00
|
|
|
'build', 'flash', 'debug', 'debugserver', 'run'). Commands to accomplish
|
|
|
|
these tasks will be generated in the right order.
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
|
2018-05-05 01:31:05 +02:00
|
|
|
\:maybe-skip-config:
|
|
|
|
if set, this indicates the reader may have already
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
created a build directory and changed there, and will tweak the text to
|
|
|
|
note that doing so again is not necessary.
|
|
|
|
|
2018-05-05 01:31:05 +02:00
|
|
|
\:compact:
|
|
|
|
if set, the generated output is a single code block with no
|
2017-11-10 13:13:27 +01:00
|
|
|
additional comment lines
|
|
|
|
|
2022-03-14 23:24:58 +01:00
|
|
|
\:west-args:
|
|
|
|
if set, additional arguments to the west invocation (ignored for CMake)
|
|
|
|
|
2023-10-20 12:05:05 +02:00
|
|
|
\:flash-args:
|
|
|
|
if set, additional arguments to the flash invocation
|
|
|
|
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
'''
|
|
|
|
has_content = False
|
|
|
|
required_arguments = 0
|
|
|
|
optional_arguments = 0
|
|
|
|
final_argument_whitespace = False
|
|
|
|
option_spec = {
|
2019-02-10 13:51:16 +01:00
|
|
|
'tool': directives.unchanged,
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
'app': directives.unchanged,
|
|
|
|
'zephyr-app': directives.unchanged,
|
2019-06-13 14:55:08 +02:00
|
|
|
'cd-into': directives.flag,
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
'generator': directives.unchanged,
|
2018-01-17 18:29:01 +01:00
|
|
|
'host-os': directives.unchanged,
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
'board': directives.unchanged,
|
2019-01-18 19:09:27 +01:00
|
|
|
'shield': directives.unchanged,
|
2017-11-10 11:42:47 +01:00
|
|
|
'conf': directives.unchanged,
|
|
|
|
'gen-args': directives.unchanged,
|
|
|
|
'build-args': directives.unchanged,
|
2023-12-03 12:43:29 +01:00
|
|
|
'snippets': directives.unchanged,
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
'build-dir': directives.unchanged,
|
2023-12-01 07:45:12 +01:00
|
|
|
'build-dir-fmt': directives.unchanged,
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
'goals': directives.unchanged_required,
|
2017-11-10 13:13:27 +01:00
|
|
|
'maybe-skip-config': directives.flag,
|
2022-03-14 23:24:58 +01:00
|
|
|
'compact': directives.flag,
|
|
|
|
'west-args': directives.unchanged,
|
2023-10-20 12:05:05 +02:00
|
|
|
'flash-args': directives.unchanged,
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
}
|
|
|
|
|
2019-02-10 13:51:16 +01:00
|
|
|
TOOLS = ['cmake', 'west', 'all']
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
GENERATORS = ['make', 'ninja']
|
2018-01-17 18:29:01 +01:00
|
|
|
HOST_OS = ['unix', 'win', 'all']
|
2019-06-13 14:55:08 +02:00
|
|
|
IN_TREE_STR = '# From the root of the zephyr repository'
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
|
|
|
|
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.
|
2019-08-25 19:06:22 +02:00
|
|
|
tool = self.options.get('tool', 'west').lower()
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
app = self.options.get('app', None)
|
|
|
|
zephyr_app = self.options.get('zephyr-app', None)
|
2019-06-13 14:55:08 +02:00
|
|
|
cd_into = 'cd-into' in self.options
|
2018-01-17 18:29:01 +01:00
|
|
|
generator = self.options.get('generator', 'ninja').lower()
|
|
|
|
host_os = self.options.get('host-os', 'all').lower()
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
board = self.options.get('board', None)
|
2019-01-18 19:09:27 +01:00
|
|
|
shield = self.options.get('shield', None)
|
2017-11-10 11:42:47 +01:00
|
|
|
conf = self.options.get('conf', None)
|
|
|
|
gen_args = self.options.get('gen-args', None)
|
|
|
|
build_args = self.options.get('build-args', None)
|
2023-12-03 12:43:29 +01:00
|
|
|
snippets = self.options.get('snippets', None)
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
build_dir_append = self.options.get('build-dir', '').strip('/')
|
2023-12-01 07:45:12 +01:00
|
|
|
build_dir_fmt = self.options.get('build-dir-fmt', None)
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
goals = self.options.get('goals').split()
|
|
|
|
skip_config = 'maybe-skip-config' in self.options
|
2017-11-10 13:13:27 +01:00
|
|
|
compact = 'compact' in self.options
|
2022-03-14 23:24:58 +01:00
|
|
|
west_args = self.options.get('west-args', None)
|
2023-10-20 12:05:05 +02:00
|
|
|
flash_args = self.options.get('flash-args', None)
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
|
2019-02-10 13:51:16 +01:00
|
|
|
if tool not in self.TOOLS:
|
|
|
|
raise self.error('Unknown tool {}; choose from: {}'.format(
|
|
|
|
tool, self.TOOLS))
|
|
|
|
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
if app and zephyr_app:
|
|
|
|
raise self.error('Both app and zephyr-app options were given.')
|
|
|
|
|
2023-12-01 07:45:12 +01:00
|
|
|
if build_dir_append != '' and build_dir_fmt:
|
|
|
|
raise self.error('Both build-dir and build-dir-fmt options were given.')
|
|
|
|
|
|
|
|
if build_dir_fmt and tool != 'west':
|
|
|
|
raise self.error('build-dir-fmt is only supported for the west build tool.')
|
|
|
|
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
if generator not in self.GENERATORS:
|
|
|
|
raise self.error('Unknown generator {}; choose from: {}'.format(
|
|
|
|
generator, self.GENERATORS))
|
|
|
|
|
2018-01-17 18:29:01 +01:00
|
|
|
if host_os not in self.HOST_OS:
|
|
|
|
raise self.error('Unknown host-os {}; choose from: {}'.format(
|
2019-02-10 13:51:50 +01:00
|
|
|
host_os, self.HOST_OS))
|
2018-01-17 18:29:01 +01:00
|
|
|
|
2017-11-10 13:13:27 +01:00
|
|
|
if compact and skip_config:
|
|
|
|
raise self.error('Both compact and maybe-skip-config options were given.')
|
|
|
|
|
2019-06-13 14:55:08 +02:00
|
|
|
app = app or zephyr_app
|
|
|
|
in_tree = self.IN_TREE_STR if zephyr_app else None
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
# Allow build directories which are nested.
|
|
|
|
build_dir = ('build' + '/' + build_dir_append).rstrip('/')
|
|
|
|
|
2018-01-17 18:29:01 +01:00
|
|
|
# Create host_os array
|
2019-02-10 21:27:11 +01:00
|
|
|
host_os = [host_os] if host_os != "all" else [v for v in self.HOST_OS
|
|
|
|
if v != 'all']
|
2019-02-10 13:51:16 +01:00
|
|
|
# Create tools array
|
|
|
|
tools = [tool] if tool != "all" else [v for v in self.TOOLS
|
|
|
|
if v != 'all']
|
2023-12-03 12:43:29 +01:00
|
|
|
|
|
|
|
# Create snippet array
|
|
|
|
snippet_list = snippets.split(',') if snippets is not None else None
|
|
|
|
|
2019-02-10 13:51:16 +01:00
|
|
|
# Build the command content as a list, then convert to string.
|
|
|
|
content = []
|
|
|
|
tool_comment = None
|
|
|
|
if len(tools) > 1:
|
2019-02-11 21:38:23 +01:00
|
|
|
tool_comment = 'Using {}:'
|
2018-01-17 18:29:01 +01:00
|
|
|
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
run_config = {
|
2019-02-10 13:51:16 +01:00
|
|
|
'host_os': host_os,
|
2019-06-13 14:55:08 +02:00
|
|
|
'app': app,
|
|
|
|
'in_tree': in_tree,
|
|
|
|
'cd_into': cd_into,
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
'board': board,
|
2019-01-18 19:09:27 +01:00
|
|
|
'shield': shield,
|
2017-11-10 11:42:47 +01:00
|
|
|
'conf': conf,
|
|
|
|
'gen_args': gen_args,
|
2019-02-10 13:51:16 +01:00
|
|
|
'build_args': build_args,
|
2023-12-03 12:43:29 +01:00
|
|
|
'snippets': snippet_list,
|
2019-02-10 13:51:16 +01:00
|
|
|
'build_dir': build_dir,
|
2023-12-01 07:45:12 +01:00
|
|
|
'build_dir_fmt': build_dir_fmt,
|
2017-11-10 13:13:27 +01:00
|
|
|
'goals': goals,
|
2019-02-10 13:51:16 +01:00
|
|
|
'compact': compact,
|
|
|
|
'skip_config': skip_config,
|
2022-03-14 23:24:58 +01:00
|
|
|
'generator': generator,
|
2023-10-20 12:05:05 +02:00
|
|
|
'west_args': west_args,
|
|
|
|
'flash_args': flash_args,
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
}
|
|
|
|
|
2019-02-10 13:51:16 +01:00
|
|
|
if 'west' in tools:
|
2019-02-11 21:38:23 +01:00
|
|
|
w = self._generate_west(**run_config)
|
2019-02-10 13:51:16 +01:00
|
|
|
if tool_comment:
|
2019-02-11 21:38:23 +01:00
|
|
|
paragraph = nodes.paragraph()
|
|
|
|
paragraph += nodes.Text(tool_comment.format('west'))
|
|
|
|
content.append(paragraph)
|
|
|
|
content.append(self._lit_block(w))
|
|
|
|
else:
|
|
|
|
content.extend(w)
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
|
2019-02-10 13:51:16 +01:00
|
|
|
if 'cmake' in tools:
|
2019-02-11 21:38:23 +01:00
|
|
|
c = self._generate_cmake(**run_config)
|
2019-02-10 13:51:16 +01:00
|
|
|
if tool_comment:
|
2019-02-11 21:38:23 +01:00
|
|
|
paragraph = nodes.paragraph()
|
|
|
|
paragraph += nodes.Text(tool_comment.format(
|
2019-09-06 11:13:19 +02:00
|
|
|
'CMake and {}'.format(generator)))
|
2019-02-11 21:38:23 +01:00
|
|
|
content.append(paragraph)
|
|
|
|
content.append(self._lit_block(c))
|
|
|
|
else:
|
|
|
|
content.extend(c)
|
|
|
|
|
|
|
|
if not tool_comment:
|
|
|
|
content = [self._lit_block(content)]
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
|
2019-02-11 21:38:23 +01:00
|
|
|
return content
|
|
|
|
|
|
|
|
def _lit_block(self, content):
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
content = '\n'.join(content)
|
|
|
|
|
|
|
|
# Create the nodes.
|
|
|
|
literal = nodes.literal_block(content, content)
|
|
|
|
self.add_name(literal)
|
2023-10-18 15:35:41 +02:00
|
|
|
literal['language'] = 'shell'
|
2019-02-11 21:38:23 +01:00
|
|
|
return literal
|
|
|
|
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
|
2019-02-10 13:51:16 +01:00
|
|
|
def _generate_west(self, **kwargs):
|
|
|
|
content = []
|
2021-02-03 14:32:44 +01:00
|
|
|
generator = kwargs['generator']
|
2019-02-10 13:51:16 +01:00
|
|
|
board = kwargs['board']
|
2019-06-13 14:55:08 +02:00
|
|
|
app = kwargs['app']
|
|
|
|
in_tree = kwargs['in_tree']
|
2019-02-10 13:51:16 +01:00
|
|
|
goals = kwargs['goals']
|
2019-06-13 14:55:08 +02:00
|
|
|
cd_into = kwargs['cd_into']
|
2019-02-10 13:51:16 +01:00
|
|
|
build_dir = kwargs['build_dir']
|
2023-12-01 07:45:12 +01:00
|
|
|
build_dir_fmt = kwargs['build_dir_fmt']
|
2019-06-13 14:55:08 +02:00
|
|
|
compact = kwargs['compact']
|
2023-12-03 12:43:29 +01:00
|
|
|
snippets = kwargs['snippets']
|
2022-03-14 23:24:58 +01:00
|
|
|
west_args = kwargs['west_args']
|
2023-10-20 12:05:05 +02:00
|
|
|
flash_args = kwargs['flash_args']
|
2019-02-10 13:51:16 +01:00
|
|
|
kwargs['board'] = None
|
2021-02-03 14:32:44 +01:00
|
|
|
# west always defaults to ninja
|
|
|
|
gen_arg = ' -G\'Unix Makefiles\'' if generator == 'make' else ''
|
|
|
|
cmake_args = gen_arg + self._cmake_args(**kwargs)
|
2019-02-10 13:51:16 +01:00
|
|
|
cmake_args = ' --{}'.format(cmake_args) if cmake_args != '' else ''
|
2022-03-14 23:24:58 +01:00
|
|
|
west_args = ' {}'.format(west_args) if west_args else ''
|
2023-10-20 12:05:05 +02:00
|
|
|
flash_args = ' {}'.format(flash_args) if flash_args else ''
|
2023-12-03 12:43:29 +01:00
|
|
|
snippet_args = ''.join(f' -S {s}' for s in snippets) if snippets else ''
|
2019-02-10 13:51:16 +01:00
|
|
|
# ignore zephyr_app since west needs to run within
|
|
|
|
# the installation. Instead rely on relative path.
|
2019-06-13 14:55:08 +02:00
|
|
|
src = ' {}'.format(app) if app and not cd_into else ''
|
2023-12-01 07:45:12 +01:00
|
|
|
|
|
|
|
if build_dir_fmt is None:
|
|
|
|
dst = ' -d {}'.format(build_dir) if build_dir != 'build' else ''
|
|
|
|
build_dst = dst
|
|
|
|
else:
|
|
|
|
app_name = app.split('/')[-1]
|
|
|
|
build_dir_formatted = build_dir_fmt.format(app=app_name, board=board, source_dir=app)
|
|
|
|
dst = ' -d {}'.format(build_dir_formatted)
|
|
|
|
build_dst = ''
|
2019-02-10 13:51:16 +01:00
|
|
|
|
2019-06-13 14:55:08 +02:00
|
|
|
if in_tree and not compact:
|
|
|
|
content.append(in_tree)
|
|
|
|
|
|
|
|
if cd_into and app:
|
|
|
|
content.append('cd {}'.format(app))
|
|
|
|
|
2019-08-28 22:50:40 +02:00
|
|
|
# We always have to run west build.
|
|
|
|
#
|
|
|
|
# FIXME: doing this unconditionally essentially ignores the
|
|
|
|
# maybe-skip-config option if set.
|
|
|
|
#
|
|
|
|
# This whole script and its users from within the
|
|
|
|
# documentation needs to be overhauled now that we're
|
|
|
|
# defaulting to west.
|
|
|
|
#
|
|
|
|
# For now, this keeps the resulting commands working.
|
2023-12-03 12:43:29 +01:00
|
|
|
content.append('west build -b {}{}{}{}{}{}'.
|
|
|
|
format(board, west_args, snippet_args, build_dst, src, cmake_args))
|
2019-08-28 22:50:40 +02:00
|
|
|
|
|
|
|
# If we're signing, we want to do that next, so that flashing
|
|
|
|
# etc. commands can use the signed file which must be created
|
|
|
|
# in this step.
|
2019-02-10 13:51:16 +01:00
|
|
|
if 'sign' in goals:
|
2019-08-28 22:50:40 +02:00
|
|
|
content.append('west sign{}'.format(dst))
|
2019-02-10 13:51:16 +01:00
|
|
|
|
|
|
|
for goal in goals:
|
2019-09-03 14:13:15 +02:00
|
|
|
if goal in {'build', 'sign'}:
|
2019-02-10 13:51:16 +01:00
|
|
|
continue
|
|
|
|
elif goal == 'flash':
|
2023-10-20 12:05:05 +02:00
|
|
|
content.append('west flash{}{}'.format(flash_args, dst))
|
2019-02-10 13:51:16 +01:00
|
|
|
elif goal == 'debug':
|
2019-08-28 22:50:40 +02:00
|
|
|
content.append('west debug{}'.format(dst))
|
2019-02-10 13:51:16 +01:00
|
|
|
elif goal == 'debugserver':
|
2019-08-28 22:50:40 +02:00
|
|
|
content.append('west debugserver{}'.format(dst))
|
2019-02-10 13:51:16 +01:00
|
|
|
elif goal == 'attach':
|
2019-08-28 22:50:40 +02:00
|
|
|
content.append('west attach{}'.format(dst))
|
2019-02-10 13:51:16 +01:00
|
|
|
else:
|
2019-08-28 22:50:40 +02:00
|
|
|
content.append('west build -t {}{}'.format(goal, dst))
|
2019-02-10 13:51:16 +01:00
|
|
|
|
|
|
|
return content
|
|
|
|
|
2019-09-04 17:04:56 +02:00
|
|
|
@staticmethod
|
|
|
|
def _mkdir(mkdir, build_dir, host_os, skip_config):
|
2018-01-17 18:29:01 +01:00
|
|
|
content = []
|
|
|
|
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
|
2019-06-13 14:55:08 +02:00
|
|
|
if host_os == 'all':
|
|
|
|
content.append('mkdir {} && cd {}'.format(build_dir, build_dir))
|
2018-01-17 18:29:01 +01:00
|
|
|
if host_os == "unix":
|
|
|
|
content.append('{} {} && cd {}'.format(mkdir, build_dir, build_dir))
|
|
|
|
elif host_os == "win":
|
2019-09-06 11:13:19 +02:00
|
|
|
build_dir = build_dir.replace('/', '\\')
|
2018-01-17 18:29:01 +01:00
|
|
|
content.append('mkdir {} & cd {}'.format(build_dir, build_dir))
|
|
|
|
return content
|
|
|
|
|
2019-09-04 17:04:56 +02:00
|
|
|
@staticmethod
|
|
|
|
def _cmake_args(**kwargs):
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
board = kwargs['board']
|
2019-01-18 19:09:27 +01:00
|
|
|
shield = kwargs['shield']
|
2017-11-10 11:42:47 +01:00
|
|
|
conf = kwargs['conf']
|
|
|
|
gen_args = kwargs['gen_args']
|
2019-02-10 13:51:16 +01:00
|
|
|
board_arg = ' -DBOARD={}'.format(board) if board else ''
|
|
|
|
shield_arg = ' -DSHIELD={}'.format(shield) if shield else ''
|
|
|
|
conf_arg = ' -DCONF_FILE={}'.format(conf) if conf else ''
|
|
|
|
gen_args = ' {}'.format(gen_args) if gen_args else ''
|
|
|
|
|
|
|
|
return '{}{}{}{}'.format(board_arg, shield_arg, conf_arg, gen_args)
|
|
|
|
|
2019-06-13 14:55:08 +02:00
|
|
|
def _cd_into(self, mkdir, **kwargs):
|
|
|
|
app = kwargs['app']
|
|
|
|
host_os = kwargs['host_os']
|
2017-11-10 13:13:27 +01:00
|
|
|
compact = kwargs['compact']
|
2019-06-13 14:55:08 +02:00
|
|
|
build_dir = kwargs['build_dir']
|
|
|
|
skip_config = kwargs['skip_config']
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
content = []
|
2019-06-13 14:55:08 +02:00
|
|
|
os_comment = None
|
|
|
|
if len(host_os) > 1:
|
|
|
|
os_comment = '# On {}'
|
|
|
|
num_slashes = build_dir.count('/')
|
|
|
|
if not app and mkdir and num_slashes == 0:
|
|
|
|
# When there's no app and a single level deep build dir,
|
|
|
|
# simplify output
|
|
|
|
content.extend(self._mkdir(mkdir, build_dir, 'all',
|
|
|
|
skip_config))
|
|
|
|
if not compact:
|
|
|
|
content.append('')
|
|
|
|
return content
|
|
|
|
for host in host_os:
|
|
|
|
if host == "unix":
|
|
|
|
if os_comment:
|
|
|
|
content.append(os_comment.format('Linux/macOS'))
|
|
|
|
if app:
|
|
|
|
content.append('cd {}'.format(app))
|
|
|
|
elif host == "win":
|
|
|
|
if os_comment:
|
|
|
|
content.append(os_comment.format('Windows'))
|
|
|
|
if app:
|
|
|
|
backslashified = app.replace('/', '\\')
|
|
|
|
content.append('cd {}'.format(backslashified))
|
|
|
|
if mkdir:
|
|
|
|
content.extend(self._mkdir(mkdir, build_dir, host, skip_config))
|
|
|
|
if not compact:
|
|
|
|
content.append('')
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
return content
|
|
|
|
|
2019-06-13 14:55:08 +02:00
|
|
|
def _generate_cmake(self, **kwargs):
|
|
|
|
generator = kwargs['generator']
|
|
|
|
cd_into = kwargs['cd_into']
|
|
|
|
app = kwargs['app']
|
|
|
|
in_tree = kwargs['in_tree']
|
|
|
|
build_dir = kwargs['build_dir']
|
2017-11-10 11:42:47 +01:00
|
|
|
build_args = kwargs['build_args']
|
2023-12-03 12:43:29 +01:00
|
|
|
snippets = kwargs['snippets']
|
2019-06-13 14:55:08 +02:00
|
|
|
skip_config = kwargs['skip_config']
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
goals = kwargs['goals']
|
2017-11-10 13:13:27 +01:00
|
|
|
compact = kwargs['compact']
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
|
2019-06-13 14:55:08 +02:00
|
|
|
content = []
|
|
|
|
|
|
|
|
if in_tree and not compact:
|
|
|
|
content.append(in_tree)
|
|
|
|
|
|
|
|
if cd_into:
|
|
|
|
num_slashes = build_dir.count('/')
|
|
|
|
mkdir = 'mkdir' if num_slashes == 0 else 'mkdir -p'
|
|
|
|
content.extend(self._cd_into(mkdir, **kwargs))
|
|
|
|
# Prepare cmake/ninja/make variables
|
|
|
|
source_dir = ' ' + '/'.join(['..' for i in range(num_slashes + 1)])
|
|
|
|
cmake_build_dir = ''
|
|
|
|
tool_build_dir = ''
|
|
|
|
else:
|
|
|
|
source_dir = ' {}'.format(app) if app else ' .'
|
2022-03-15 23:30:00 +01:00
|
|
|
cmake_build_dir = ' -B{}'.format(build_dir)
|
|
|
|
tool_build_dir = ' -C{}'.format(build_dir)
|
2019-06-13 14:55:08 +02:00
|
|
|
|
|
|
|
# Now generate the actual cmake and make/ninja commands
|
|
|
|
gen_arg = ' -GNinja' if generator == 'ninja' else ''
|
2017-11-10 11:42:47 +01:00
|
|
|
build_args = ' {}'.format(build_args) if build_args else ''
|
2023-12-03 12:43:29 +01:00
|
|
|
snippet_args = ' -DSNIPPET="{}"'.format(';'.join(snippets)) if snippets else ''
|
2019-02-10 13:51:16 +01:00
|
|
|
cmake_args = self._cmake_args(**kwargs)
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
|
2019-06-13 14:55:08 +02:00
|
|
|
if not compact:
|
|
|
|
if not cd_into and skip_config:
|
|
|
|
content.append("# If you already ran cmake with -B{}, you " \
|
|
|
|
"can skip this step and run {} directly.".
|
|
|
|
format(build_dir, generator)) # noqa: E501
|
|
|
|
else:
|
|
|
|
content.append('# Use cmake to configure a {}-based build' \
|
|
|
|
'system:'.format(generator.capitalize())) # noqa: E501
|
|
|
|
|
2023-12-03 12:43:29 +01:00
|
|
|
content.append('cmake{}{}{}{}{}'.format(cmake_build_dir, gen_arg,
|
|
|
|
cmake_args, snippet_args, source_dir))
|
2017-11-10 13:13:27 +01:00
|
|
|
if not compact:
|
2017-11-10 18:42:33 +01:00
|
|
|
content.extend(['',
|
2023-11-16 15:03:07 +01:00
|
|
|
'# Now run the build tool on the generated build system:'])
|
2019-06-13 14:55:08 +02:00
|
|
|
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
if 'build' in goals:
|
2019-06-13 14:55:08 +02:00
|
|
|
content.append('{}{}{}'.format(generator, tool_build_dir,
|
|
|
|
build_args))
|
2017-11-10 18:44:57 +01:00
|
|
|
for goal in goals:
|
|
|
|
if goal == 'build':
|
|
|
|
continue
|
2019-06-13 14:55:08 +02:00
|
|
|
content.append('{}{} {}'.format(generator, tool_build_dir, goal))
|
2019-02-10 13:51:16 +01:00
|
|
|
|
|
|
|
return content
|
|
|
|
|
doc: add zephyr-app-commands directive
Add extensions/zephyr to the documentation. This is where Sphinx
extensions customized for Zephyr will live.
Within, add application.py. This provides a directive,
zephyr-app-commands, which generates commands in the docs to build,
flash, debug, etc. an application. For now, these are Unix shell
specific. Later on, they can be customized to generate additional
formats, perhaps with extra options.
After this is used throughout the tree, doing this with an extension
enables global changes with changes to the directive implementation
only.
Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
2017-11-03 21:46:33 +01:00
|
|
|
|
|
|
|
def setup(app):
|
|
|
|
app.add_directive('zephyr-app-commands', ZephyrAppCommandsDirective)
|
|
|
|
|
|
|
|
return {
|
|
|
|
'version': '1.0',
|
|
|
|
'parallel_read_safe': True,
|
|
|
|
'parallel_write_safe': True
|
|
|
|
}
|