From d549200c58887411a60d472e0e5d0c4d2e247ff0 Mon Sep 17 00:00:00 2001 From: vector-of-bool Date: Sat, 25 Jun 2022 18:46:02 -0600 Subject: [PATCH] Doc spelling grammar tweaks --- docs/conf.py | 3 --- docs/crs/index.rst | 2 +- docs/design.rst | 6 ++--- docs/dev/reqs.rst | 9 ++++--- docs/dev/testing.rst | 2 +- docs/guide/build-deps.rst | 8 +++--- docs/guide/cmake.rst | 11 ++++---- docs/guide/deps.rst | 6 +++++ docs/guide/terms.rst | 4 +++ docs/guide/toolchains.rst | 57 +++++++++++++++++++++++++-------------- docs/howto/cmake.rst | 10 +++---- 11 files changed, 71 insertions(+), 47 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 78fe1d9a..486bbb21 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -150,7 +150,6 @@ def add_target_and_index(self, name: tuple[_FullNameStr, _Ident], sig: str, sign self.state.document.note_explicit_target(signode) dom = cast(SchematicDomain, self.env.get_domain('schematic')) - print(f'Saving {self.objtype} {fullname}') assert self.objtype in ('property', 'mapping') dom.data['objects'][fullname] = { 'parent': _dotpath(self.env), @@ -391,7 +390,6 @@ def find_obj(self, node: addnodes.pending_xref, name: str) -> _SchematicEntry | else: partials = [name] for cand in partials: - print('Looking for fullnamed object:', cand) found = self.data['objects'].get(cand) if found is not None: return found @@ -400,7 +398,6 @@ def find_obj(self, node: addnodes.pending_xref, name: str) -> _SchematicEntry | def resolve_xref(self, env: BuildEnvironment, fromdocname: str, builder: Builder, typ: Literal['mapping', 'prop'], target: str, node: addnodes.pending_xref, contnode: Element): - ident = f'{typ}:{target}' ent: _SchematicEntry | None ent = self.find_obj(node, target) if ent is None: diff --git a/docs/crs/index.rst b/docs/crs/index.rst index d7a7d98f..3d7b67fe 100644 --- a/docs/crs/index.rst +++ b/docs/crs/index.rst @@ -51,7 +51,7 @@ Briefly, `CRS` concerns itself with the following high-level concepts: An acronym for :strong:`C`\ ompile-\ :strong:`R`\ eady :strong:`S`\ ource. CRS is a set of file formats and `JSON` schemas that describe a way to - destribute software in source-code format, ready to be given to any + distribute software in source-code format, ready to be given to any compatible compiler without further configuration or code generation. .. seealso:: :doc:`index` diff --git a/docs/design.rst b/docs/design.rst index 92878514..458c6f8f 100644 --- a/docs/design.rst +++ b/docs/design.rst @@ -183,7 +183,7 @@ No Arbitrary |#include| Directories =================================== Only ``src/`` and ``include/`` will ever be used as the basis for -`header resolution
` while building a project, so all +:term:`header resolution
` while building a project, so all |#include| directives should be relative to those directories. Refer to :ref:`libs.source-kinds`. @@ -199,5 +199,5 @@ every library in that dependency tree will be compiled with an identical set of options. Refer to the :doc:`guide/toolchains` page for more information. Currently, the only exception to this rules is for flags that control compiler -warnings: Dependencies will be compiled without adding any warnings flags, while -the main project will be compiled with warnings enabled by default. +diagnostics: Dependencies will be compiled without adding any warnings flags, +while the main project will be compiled with warnings enabled by default. diff --git a/docs/dev/reqs.rst b/docs/dev/reqs.rst index 7755d7e2..917710f9 100644 --- a/docs/dev/reqs.rst +++ b/docs/dev/reqs.rst @@ -13,10 +13,11 @@ Build Requirements Building |bpt| has a simple set of requirements: - **Python 3.7** or newer to run the bootstrap/CI scripts. -- A C++ compiler that has rudimentary support for several C++20 features, - including Concepts. Newer releases of Visual C++ that ship with **VS 2019** - will be sufficient on Windows, as will **GCC 10** with ``-std=c++20`` and - ``-fcoroutines`` on other platforms. +- A C++ compiler that has rudimentary support for several C++20 features. Newer + releases of Visual C++ that ship with **VS 2019** will be sufficient on + Windows, as will **GCC 10** with ``-std=c++20`` and ``-fcoroutines`` on other + platforms. **Note:** Using newer compiler versions may cause trouble as they + are untested, but adding support for these systems is planned. - On Linux, the OpenSSL headers are needed. This can be installed through the ``libssl-dev`` package on Debian/Ubuntu or ``openss-devel`` + ``openssl-static`` on RedHat systems. (For Windows, the |bpt| repository ships diff --git a/docs/dev/testing.rst b/docs/dev/testing.rst index c0b1d664..4891e7ab 100644 --- a/docs/dev/testing.rst +++ b/docs/dev/testing.rst @@ -13,7 +13,7 @@ within the :doc:`Poetry virtual environment `:: Note that individual tests can take between a few seconds and a few minutes to execute, so it may be useful to execute only a subset of the tests based on the functionality you want to test. Refer to -`the pytest documentation ` for more +`the pytest documentation `_ for more information about using and executing ``pytest``. If you are running the full test suite, you may also want to pass the ``-n`` argument with a number of parallel jobs to execute. diff --git a/docs/guide/build-deps.rst b/docs/guide/build-deps.rst index a63bd7ed..60e556ce 100644 --- a/docs/guide/build-deps.rst +++ b/docs/guide/build-deps.rst @@ -27,7 +27,7 @@ is not generated globally**: It is generated on a per-build basis as part of the build process. The manifest will describe in build-system-agnostic terms how to include and link against as set of libraries generated by a build. -|bpt| has first-class support for generating this index. The ``build-deps`` +|bpt| has first-class support for generating this file. The ``build-deps`` subcommand of |bpt| will download and build a set of dependencies, and places a `JSON` file that can be used to import the built results. @@ -50,9 +50,9 @@ Declaring Dependencies in a File `dependency specifiers ` as command line arguments, but it may be useful to specify those requirements in a file. -``bpt build-deps`` accepts a YAML file describing the dependencies of a project -as well. The only required property in the file is the ``dependencies`` key. -(The presence of any other key is an error.) +``bpt build-deps`` accepts a `YAML` file describing the dependencies of a +project as well. The only required property in the file is the ``dependencies`` +key. (The presence of any other key is an error.) Here is a simple dependencies file that declares a single requirement: diff --git a/docs/guide/cmake.rst b/docs/guide/cmake.rst index 331040e9..356a56e5 100644 --- a/docs/guide/cmake.rst +++ b/docs/guide/cmake.rst @@ -6,7 +6,7 @@ Using |bpt| in a CMake Project .. default-role:: term One of |bpt|'s primary goals is to inter-operate with other build systems -cleanly. Because of `CMakes ` ubiquity, |bpt| includes built-in support +cleanly. Because of `CMake's ` ubiquity, |bpt| includes built-in support for emitting files that can be imported into CMake. .. seealso:: @@ -51,11 +51,10 @@ Like with |bpt|, CMake wants us to explicitly declare how our build targets *use* other libraries. When we ``include()`` the generated CMake file, it will generate ``IMPORTED`` targets that can be linked against. -In |bpt| (and in libman), a library is identified by a combination of -*namespace* and *name*, joined together with a slash ``/`` character. This -*qualified name* of a library is decided by the original package author, and -should be documented. In the case of ``neo-sqlite3``, the only library is -``neo/sqlite3``. +In |bpt|, a library is identified by a combination of *namespace* and *name*, +joined together with a slash ``/`` character. This *qualified name* of a library +is decided by the original package author, and should be documented. In the case +of ``neo-sqlite3``, the only library is ``neo/sqlite3``. When the generated import file imports a library, it creates a qualified name using a double-colon "``::``" instead of a slash. As such, our ``neo/sqlite3`` diff --git a/docs/guide/deps.rst b/docs/guide/deps.rst index 4b439662..8518d387 100644 --- a/docs/guide/deps.rst +++ b/docs/guide/deps.rst @@ -193,6 +193,12 @@ Besides requiring that a candidate for dependency resolution meet the version requirements, the candidate must also provide all of the libraries named by the :cpp:`using` specifier on the dependency statement. +.. note:: + + If you omit the :cpp:`using` specifier, it is equivalent to :cpp:`using` a + library with the same name as the package. (This would be the + `default library` of the package.) + .. default-role:: math A Simple Example diff --git a/docs/guide/terms.rst b/docs/guide/terms.rst index d16ac745..bc2619ff 100644 --- a/docs/guide/terms.rst +++ b/docs/guide/terms.rst @@ -34,6 +34,10 @@ This page documents miscellaneous terminology used throughout |bpt| and `CRS`. JSON data cannot contain comments. The order of keys within a JSON object is not significant. + JSON5 + + A superset of `JSON` that permits comments, single-quote strings, multi-line + strings, trailing commas, and bare identifier keys. YAML diff --git a/docs/guide/toolchains.rst b/docs/guide/toolchains.rst index c737be13..ef2c6629 100644 --- a/docs/guide/toolchains.rst +++ b/docs/guide/toolchains.rst @@ -1,4 +1,4 @@ -.. highlight:: js +.. highlight:: yaml .. default-domain:: schematic .. default-role:: schematic:prop @@ -37,15 +37,14 @@ effectively in your project. Passing a Toolchain ******************* -In |bpt|, the default format of a toolchain is that of a single JSON5 file -that describes the entire toolchain. When running a build for a project, the -|bpt| executable will look in a few locations for a default toolchain, and +In |bpt|, the default format of a toolchain is that of a single :term:`YAML` +file that describes the entire toolchain. When running a build for a project, +the |bpt| executable will look in a few locations for a default toolchain, and generate an error if no default toolchain file is found (Refer to -:ref:`toolchains.default`). A different toolchain can be provided by passing -the toolchain file for the |--toolchain| (or ``-t``) option on the command -line:: +:ref:`toolchains.default`). A different toolchain can be provided by passing the +toolchain file for the |--toolchain| (or ``-t``) option on the command line:: - $ bpt build -t my-toolchain.json5 + $ bpt build -t my-toolchain.yaml Alternatively, you can pass the name of a built-in toolchain. See below. @@ -106,16 +105,16 @@ The following directories are searched, in order: #. ``$pwd/`` - If the working directory contains a toolchain file, it will be used as the default. -#. ``$bpt_config_dir/`` - Searches for a toolchain file in |bpt|'s user-local +#. ``/`` - Searches for a toolchain file in |bpt|'s user-local configuration directory (see below). -#. ``$user_home/`` - Searches for a toolchain file at the root of the current +#. ``/`` - Searches for a toolchain file at the root of the current user's home directory. (``$HOME`` on Unix-like systems, and ``$PROFILE`` on Windows.) -In each directory, it will search for ``toolchain.json5``, ``toolchain.jsonc``, -or ``toolchain.json``. +In each directory, it will search for ``toolchain.yaml``, ``toolchain.json5``, +``toolchain.jsonc``, or ``toolchain.json``. -The ``$bpt_config_dir`` directory is the |bpt| subdirectory of the user-local +The ```` directory is the |bpt| subdirectory of the user-local configuration directory. The user-local config directory is ``$XDG_CONFIG_DIR`` or ``~/.config`` on @@ -184,14 +183,21 @@ Flags for linking executables can be specified with } +.. note:: + + Command/flag list settings are subject to shell-like string splitting. String + splitting can be suppressed by using an array instead of a string. Refer: + :ref:`tc-splitting-note`. + .. _toolchains.opt-ref: Toolchain Option Reference ************************** +.. _tc-splitting-note: Understanding Flags and Shell Parsing -------------------------------------- +===================================== Many of the |bpt| toolchain parameters accept argument lists or shell-string lists. If such an option is given a single string, then that string is split @@ -217,6 +223,10 @@ Despite splitting strings as-if they were shell commands, |bpt| does nothing else shell-like. It does not expand environment variables, nor does it expand globs and wildcards. + +Toolchain Options Schema +======================== + .. mapping:: ToolchainOptions .. property:: compiler_id @@ -248,7 +258,7 @@ globs and wildcards. .. property:: cxx_compiler :optional: - :type: string + :type: :ts:`string` Names/paths of the C and C++ compilers, respectively. @@ -271,6 +281,8 @@ globs and wildcards. .. property:: cxx_version :optional: + :type: :ts:`string` + Specify the language versions for C and C++, respectively. By default, |bpt| will not set any language version. Using this option requires that the :prop:`~ToolchainOptions.compiler_id` be specified (Or the @@ -303,6 +315,7 @@ globs and wildcards. ``/std:c++latest``. **Beware** that this is an unstable setting value that could change the major language version in a future MSVC update. + .. property:: warning_flags :optional: @@ -323,7 +336,7 @@ globs and wildcards. .. seealso:: - Refer to :prop:`AdvancedToolchainOptions.base_warning_flags` for more + Refer to :prop:`~AdvancedToolchainOptions.base_warning_flags` for more information. @@ -378,13 +391,13 @@ globs and wildcards. Generates debug information embedded in the compiled binaries. - :option split: + :option "split": Generates debug information in a separate file from the compiled binaries. .. note:: - ``"split"`` with GCC requires that the compiler support the + ``"split"`` with GCC/Clang requires that the compiler support the ``-gsplit-dwarf`` option. :option true: Same as :ts:`"embedded"` @@ -427,7 +440,7 @@ globs and wildcards. .. note:: - On GNU-like compilers, setting :prop:`ToolchainOptions.runtime.static` to + On GNU-like compilers, setting :prop:`~ToolchainOptions.runtime.static` to |true| does not generate a static executable: it only statically links the runtime and standard library. To generate a static executable, the ``-static`` option should be added to ``link_flags``. @@ -571,10 +584,14 @@ Advanced Options Reference The placeholder for the output path for the executable file. + :placeholder [flags]: + + Placeholder for options specified using `~ToolchainOptions.link_flags`. + :default: |default-inferred-from-compiler_id|: - If |compiler_id| is |msvc|, then - `` /nologo /EHsc [in] /Fe[out]`` + `` /nologo /EHsc [in] /Fe[out] [flags]`` - If |compiler_id| is |gnu| or |clang|, then `` -fPIC [in] -pthread -o[out] [flags]`` - If |compiler_id| is unset, then this property must be specified. diff --git a/docs/howto/cmake.rst b/docs/howto/cmake.rst index 83b84dd5..7df97f2c 100644 --- a/docs/howto/cmake.rst +++ b/docs/howto/cmake.rst @@ -79,13 +79,13 @@ for now. The basic signature of the ``pmm(BPT)`` command looks like this:: pmm(BPT [DEP_FILES [filepaths...]] - [DEPENDS [dependencies...]] + [DEPENDENCIES [dependencies...]] [TOOLCHAIN file-or-id]) -The most straightforward usage is to use only the ``DEPENDS`` argument. For +The most straightforward usage is to use only the ``DEPENDENCIES`` argument. For example, if we want to import `{fmt} `_:: - pmm(BPT DEPENDS "fmt@7.0.3") + pmm(BPT DEPENDENCIES "fmt@7.0.3") When CMake executes the ``pmm(BPT ...)`` line above, PMM will download the appropriate |bpt| executable for your platform, generate @@ -140,7 +140,7 @@ In all, this is our final ``CMakeLists.txt``: project(MYApplication VERSION 2.1.3) include(tools/pmm.cmake) - pmm(BPT DEPENDS fmt@7.0.3) + pmm(BPT DEPENDENCIES fmt@7.0.3) add_executable(my-application app.cpp) target_link_libraries(my-application PRIVATE fmt::fmt) @@ -153,7 +153,7 @@ Changing Compile Options :doc:`toolchains `. PMM supports specifying a toolchain using the ``TOOLCHAIN`` argument:: - pmm(BPT DEPENDS fmt@7.0.3 TOOLCHAIN my-toolchain.json5) + pmm(BPT DEPENDENCIES fmt@7.0.3 TOOLCHAIN my-toolchain.json5) Of course, writing a separate toolchain file just for your dependencies can be tedious. For this reason, PMM will write a toolchain file on-the-fly when it