Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update and sort settings documentation #1130

Merged
merged 3 commits into from
Apr 2, 2020
Merged

Update and sort settings documentation #1130

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c03ec31
Add cmake.parallelJobs to settings documentation
karolinschlegel Mar 18, 2020
d4fb9ed
Sort the settings in alphabetical order
karolinschlegel Mar 18, 2020
ef03826
Edit cmake.parallelJobs
karolinschlegel Apr 2, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
229 changes: 118 additions & 111 deletions docs/settings.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,17 +16,19 @@ in their strings. See the :ref:`var-subs` section
Available Settings
==================

.. _conf-cmake.buildDirectory:
.. _conf-cmake.buildArgs:

``cmake.buildDirectory``
************************
``cmake.buildArgs``
*******************

Specify the build directory (The root directory where ``CMakeCache.txt`` will
be generated).
An array of additional arguments to pass to ``cmake --build``.

- Default: ``${workspaceFolder}/build``.
- Default: ``[]`` (Empty array, no additional arguments)
- *Supports substitution*

.. seealso::
- :ref:`building.how`

.. _conf-cmake.buildBeforeRun:

``cmake.buildBeforeRun``
Expand All @@ -36,76 +38,40 @@ If ``true``, build the launch/debug target before letting it execute.

- Default: ``true``

.. _conf-cmake.cmakePath:

``cmake.cmakePath``
*******************

Specify location of the cmake executable.

- Default: ``cmake``, which causes CMake Tools to search the ``PATH`` environment
variable, as well as some hard-coded guesses.
- *Supports substitution* of ``workspaceRoot``, ``workspaceFolder``, ``workspaceRootFolderName``,
``userHome``, ``${command:...}`` and ``${env:...}``. Other substitutions will
result in empty string.

.. _conf-cmake.installPrefix:

``cmake.installPrefix``
***********************

If specified, sets a value for ``CMAKE_INSTALL_PREFIX`` when running CMake
configure. If not, no value will be passed.

- Default: ``null`` (Unspecified)
- *Supports substitution*

.. note::
If ``CMAKE_INSTALL_PREFIX`` is set via ``cmake.configureArgs`` or
``cmake.configureSettings``, ``cmake.installPrefix`` will be ignored.
.. _conf-cmake.buildDirectory:

``cmake.sourceDirectory``
*************************
``cmake.buildDirectory``
************************

Directory where the root ``CMakeLists.txt`` will be found.
Specify the build directory (The root directory where ``CMakeCache.txt`` will
be generated).

- Default: ``${workspaceFolder}``
- Default: ``${workspaceFolder}/build``.
- *Supports substitution*

.. _conf-cmake.buildEnvironment:

``cmake.saveBeforeBuild``
*************************

If ``true`` (the default), saves open text documents when build or configure is
invoked before running CMake.

- Default: ``true``

.. _conf-cmake.configureSettings:

``cmake.configureSettings``
``cmake.buildEnvironment``
***************************

An object containing ``key : value`` pairs, which will be
passed onto CMake when configuring.
It does the same thing as passing ``-DVAR_NAME=ON`` via
``cmake.configureArgs``.
An object containing ``key : value`` pairs of environment variables,
which will be passed *ONLY* onto the compiler.

- Default: ``null`` (Unspecified)
- *Supports substitution*

.. _conf-cmake.configureArgs:
.. _conf-cmake.buildToolArgs:

``cmake.configureArgs``
``cmake.buildToolArgs``
***********************

Arguments to CMake that will be passed during the configure process.
An array of additional arguments to pass to *the underlying build tool*.

- Default: ``[]`` (Empty array, no arguments)
- Default: ``[]`` (Empty array, no additional arguments)
- *Supports substitution*

.. warning::
**Always** prefer to use ``cmake.configureSettings`` or :ref:`variants`.
*Never* pass ``-D`` arguments using this setting.
.. seealso::
- :ref:`building.how`

.. _conf-cmake.cacheInit:

Expand All @@ -117,27 +83,33 @@ Path or list of paths to cache-initialization files. Passed to CMake via the

- Default: ``[]`` (Empty array, no cache initializer files)

.. _conf-cmake.mingwSearchDirs:
.. _conf-cmake.cmakePath:

``cmake.mingwSearchDirs``
*************************
``cmake.cmakePath``
*******************

List of paths to search for a MinGW installation. This means that GCC does not
need to be on your ``$PATH`` for it to be found via Kit scanning.
Specify location of the cmake executable.

- Default: ``["C:\\MinGW"]`` (Search in C:\\MinGW for a MinGW installation)
- Default: ``cmake``, which causes CMake Tools to search the ``PATH`` environment
variable, as well as some hard-coded guesses.
- *Supports substitution* of ``workspaceRoot``, ``workspaceFolder``, ``workspaceRootFolderName``,
``userHome``, ``${command:...}`` and ``${env:...}``. Other substitutions will
result in empty string.

.. _conf-cmake.environment:
.. _conf-cmake.configureArgs:

``cmake.environment``
*********************
``cmake.configureArgs``
***********************

An object containing ``key : value`` pairs of environment variables,
which will be passed onto CMake when configuring and to the compiler.
Arguments to CMake that will be passed during the configure process.

- Default: ``null`` (Unspecified)
- Default: ``[]`` (Empty array, no arguments)
- *Supports substitution*

.. warning::
**Always** prefer to use ``cmake.configureSettings`` or :ref:`variants`.
*Never* pass ``-D`` arguments using this setting.

.. _conf-cmake.configureEnvironment:

``cmake.configureEnvironment``
Expand All @@ -149,50 +121,48 @@ which will be passed onto CMake *ONLY* when configuring.
- Default: ``null`` (Unspecified)
- *Supports substitution*

.. _conf-cmake.buildEnvironment:
.. _conf-cmake.configureSettings:

``cmake.buildEnvironment``
``cmake.configureSettings``
***************************

An object containing ``key : value`` pairs of environment variables,
which will be passed *ONLY* onto the compiler.
An object containing ``key : value`` pairs, which will be
passed onto CMake when configuring.
It does the same thing as passing ``-DVAR_NAME=ON`` via
``cmake.configureArgs``.

- Default: ``null`` (Unspecified)
- *Supports substitution*

.. _conf-cmake.buildArgs:
.. _conf-cmake.copyCompileCommands:

``cmake.buildArgs``
*******************
``cmake.copyCompileCommands``
*****************************

An array of additional arguments to pass to ``cmake --build``.
If not ``null``, copies the ``compile_commands.json`` file generated by CMake
to the path specified by this setting every time CMake successfully configures.

- Default: ``[]`` (Empty array, no additional arguments)
- Default: ``null`` (Do not copy the file)
- *Supports substitution*

.. seealso::
- :ref:`building.how`

.. _conf-cmake.buildToolArgs:

``cmake.buildToolArgs``
***********************
.. _conf-cmake.defaultVariants:

An array of additional arguments to pass to *the underlying build tool*.
``cmake.defaultVariants``
*************************

- Default: ``[]`` (Empty array, no additional arguments)
- *Supports substitution*
Override the default set of variants that will be supplied when no variants file
is present. See :ref:`variants`.

.. seealso::
- :ref:`building.how`
.. _conf-cmake.environment:

.. _conf-cmake.preferredGenerators:
``cmake.environment``
*********************

``cmake.preferredGenerators``
*****************************
An object containing ``key : value`` pairs of environment variables,
which will be passed onto CMake when configuring and to the compiler.

A list of strings of generator names to try in order when configuring a CMake
project for the first time.
- Default: ``null`` (Unspecified)
- *Supports substitution*

.. _conf-cmake.generator:

Expand All @@ -203,25 +173,21 @@ Set to a string to override CMake Tools' *preferred generator* logic. If this is
set, CMake will unconditionally use it as the ``-G`` CMake generator command
line argument.

.. _conf-cmake.defaultVariants:

``cmake.defaultVariants``
*************************

Override the default set of variants that will be supplied when no variants file
is present. See :ref:`variants`.

.. _conf-cmake.copyCompileCommands:
.. _conf-cmake.installPrefix:

``cmake.copyCompileCommands``
*****************************
``cmake.installPrefix``
***********************

If not ``null``, copies the ``compile_commands.json`` file generated by CMake
to the path specified by this setting every time CMake successfully configures.
If specified, sets a value for ``CMAKE_INSTALL_PREFIX`` when running CMake
configure. If not, no value will be passed.

- Default: ``null`` (Do not copy the file)
- Default: ``null`` (Unspecified)
- *Supports substitution*

.. note::
If ``CMAKE_INSTALL_PREFIX`` is set via ``cmake.configureArgs`` or
``cmake.configureSettings``, ``cmake.installPrefix`` will be ignored.

.. _conf-cmake.loggingLevel:

``cmake.loggingLevel``
Expand All @@ -238,6 +204,47 @@ produces in its output channel. Set to one of "trace", "debug", "info", "note",
to the CMake Tools log file. This file is useful for
:ref:`troubleshooting <troubleshooting>`.

.. _conf-cmake.mingwSearchDirs:

``cmake.mingwSearchDirs``
*************************

List of paths to search for a MinGW installation. This means that GCC does not
need to be on your ``$PATH`` for it to be found via Kit scanning.

- Default: ``["C:\\MinGW"]`` (Search in C:\\MinGW for a MinGW installation)

.. _conf-cmake.parallelJobs:

``cmake.parallelJobs``
**********************

By specifying a number, you can define how many jobs are run in parallel during the build.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would probably say that this controls how many CPU cores are used during the build. -j is passed to build tools that support it, but not all do. I believe msbuild uses /maxcpucount:. I think if you just say that this controls the number of CPU cores used during the build, that should be sufficient.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You're right. I changed it.


.. _conf-cmake.preferredGenerators:

``cmake.preferredGenerators``
*****************************

A list of strings of generator names to try in order when configuring a CMake
project for the first time.

``cmake.saveBeforeBuild``
*************************

If ``true`` (the default), saves open text documents when build or configure is
invoked before running CMake.

- Default: ``true``

``cmake.sourceDirectory``
*************************

Directory where the root ``CMakeLists.txt`` will be found.

- Default: ``${workspaceFolder}``
- *Supports substitution*

.. _var-subs:

Variable Substitution
Expand Down