Remove old doc markdown and direct users to the official docs
This commit is contained in:
vector-of-bool
Родитель
a85a1c4c21
Коммит
836ecd917f
|
|
@ -0,0 +1,5 @@
|
|||
# CMake Tools Documentation
|
||||
|
||||
If you are an end user that has come looking for the CMake Tools documentation, you probably want to take a look at it in rendered HTML form:
|
||||
|
||||
[Click here to go to the official end-user CMake Tools Documentation](https://vector-of-bool.github.io/docs/vscode-cmake-tools/index.html).
|
||||
|
|
@ -1,158 +0,0 @@
|
|||
# Build Variants
|
||||
|
||||
Some build systems support build variants as a way to represent a commonly used
|
||||
set of build settings and ways to mix and match them. ``cmake-variants.json``
|
||||
(or a YAML variant, ``cmake-variants.yaml``) provides a way to encode a set of
|
||||
project build settings to users in a way that is convenient, descriptive, and
|
||||
easy to use. CMake Tools 0.6.0 features full support for working with variants
|
||||
in this manner.
|
||||
|
||||
## ``cmake-variants.json``
|
||||
|
||||
The most important part of the system is ``cmake-variants.json``, which encodes
|
||||
available build settings in such a way that they can be parsed and analyzed by
|
||||
automated tooling, as well as human users. Here is the default variants
|
||||
configuration used by CMake Tools when one is not present in a project directory:
|
||||
|
||||
~~~json
|
||||
{
|
||||
"buildType": {
|
||||
"default$": "debug",
|
||||
"description$": "the build type to use",
|
||||
"debug": {
|
||||
"oneWordSummary$": "Debug",
|
||||
"description$": "Emit debug information without performing optimizations",
|
||||
"buildType": "Debug"
|
||||
},
|
||||
"release": {
|
||||
"oneWordSummary$": "Release",
|
||||
"description$": "Enable optimizations, omit debug info",
|
||||
"buildType": "Release"
|
||||
},
|
||||
"minsize": {
|
||||
"oneWordSummary$": "MinSizeRel",
|
||||
"description$": "Optimize for smallest binary size",
|
||||
"buildType": "MinSizeRel"
|
||||
},
|
||||
"reldeb": {
|
||||
"oneWordSummary$": "RelWithDebInfo",
|
||||
"description$": "Perform optimizations AND include debugging information",
|
||||
"buildType": "RelWithDebInfo"
|
||||
}
|
||||
}
|
||||
}
|
||||
~~~
|
||||
|
||||
This variants file simply exposes the four default CMake build type settings
|
||||
available.
|
||||
|
||||
In Code, CMake Tools generates the following simple quick-pick when we ask to
|
||||
change the build variant:
|
||||
|
||||
|
||||
|
||||
In short, the variants file specifies a set of _options_ and the corresponding
|
||||
_values_ that they can assume. In the above example, there is one _option_
|
||||
called ``buildType``. The inner keys describe the option and the values it can
|
||||
assume. Special keys are suffixed by the ``$`` symbol, and are not valid
|
||||
values for variant option. The special ``default$`` key specifies what the
|
||||
default value for that option will be. The ``description$`` property will
|
||||
describe what aspects of the build that the option controls.
|
||||
|
||||
All other properties are values available for that key. In the above example,
|
||||
the values available for the ``buildType`` settings are ``debug``, ``release``,
|
||||
``minsize``, and ``reldeb``. The values within this keys specify the effects of
|
||||
choosing that specific value for the option. There are some pre-defined keys
|
||||
that are valid in this location, specified below.
|
||||
|
||||
### Multiple Dimensions
|
||||
|
||||
Variants create a multi-dimensional array of possible build configurations. The
|
||||
rank of the array will be the number of options available to be set. The size
|
||||
of each dimension corresponds to the number of values that are available for
|
||||
the corresponding option. The available variants are the cartesian product of
|
||||
the options and their values. For example, we can add a ``linkage`` setting to
|
||||
the above ``cmake-variants.json`` file:
|
||||
|
||||
~~~json
|
||||
{
|
||||
"buildType": {
|
||||
/* ... */
|
||||
},
|
||||
"linkage": {
|
||||
"default$": "static",
|
||||
"description$": "The link usage of build libraries",
|
||||
"static": {
|
||||
"oneWordSummary$": "Static",
|
||||
"description$": "Emit Static Libraries",
|
||||
"linkage": "static"
|
||||
},
|
||||
"shared": {
|
||||
"oneWordSummary$": "Shared",
|
||||
"description$": "Emit shared libraries/DLLs",
|
||||
"linkage": "shared"
|
||||
}
|
||||
}
|
||||
}
|
||||
~~~
|
||||
|
||||
This creates a more complex quick-pick, containing each combination of build
|
||||
type and link mode:
|
||||
|
||||
|
||||
|
||||
Automated tools can use this information to configure, build and analyze
|
||||
projects in an exhaustive and thorough manner. Humans can read the file and get
|
||||
a pretty good idea of what options are available to them.
|
||||
|
||||
## Available settings
|
||||
|
||||
Each value of a variant option can specify arbitrary build settings (meaning
|
||||
that two values within an option don't need to be symmetrically or mutually
|
||||
exclusive). When a set of options and corresponding valus are selected by a user
|
||||
or tool, the resulting settings correspond to the result of merging the
|
||||
settings specified in each chosen value. Here is a short listing of the settings
|
||||
which can be provided:
|
||||
|
||||
- ``oneWordSummary$`` is a one-word summary of the value. This should be short and
|
||||
on-point. This is displayed to the user when a variant is given a name. Good
|
||||
examples might be "Debug", "Optimized", "DebugAssertions", "UseSuperAwefulHack",
|
||||
"UseExtremelySuperAwefulHack". *Bad* values might be "Emit debug symbols",
|
||||
"Link with shared libraries". Those should go in ``description$``.
|
||||
|
||||
- ``description$`` is a lengthier description about what a setting does. Users can
|
||||
inspect this value for more information about why they may or may not want
|
||||
to use the given value.
|
||||
|
||||
- ``buildType`` specifies what build type to use. This is the value passed for
|
||||
``CMAKE_BUILD_TYPE`` and the ``--config`` option when invoking
|
||||
``cmake --build``. **Note** that this should be preferred to setting
|
||||
``CMAKE_BUILD_TYPE`` manually in the ``settings`` property (described below).
|
||||
|
||||
- ``linkage`` specifies what should be passed to CMake for
|
||||
[the BUILD_SHARED_LIBS option](https://cmake.org/cmake/help/latest/variable/BUILD_SHARED_LIBS.html),
|
||||
which *should be preferred* as the option to use for library projects which
|
||||
can be built as either static or shared/dynamic libraries.
|
||||
|
||||
- ``settings`` is the most expressive option: It specifies the exact values that
|
||||
are passed to CMake using the ``-D`` option. It should simply be a mapping of
|
||||
variable names and values that will be passed to CMake at configure time.
|
||||
*Note* that ``buildType``, ``linkage``, and other similar top-level options
|
||||
should be preferred to specifying their corresponding CMake options here.
|
||||
|
||||
A quick example:
|
||||
|
||||
~~~json
|
||||
"settings": {
|
||||
"MY_CMAKE_CONFIG_OPTION": "Some Value",
|
||||
"RANDOM_NUMBER": 4,
|
||||
}
|
||||
~~~
|
||||
|
||||
This can be used to specify strings, numbers, boolean values, or string arrays.
|
||||
|
||||
- ``generator`` specifies what ``-G`` generator to use for configuring. Note
|
||||
that it is **not yet supported by CMake Tools**.
|
||||
|
||||
- ``toolset`` specifies what toolset to use with the ``-T`` option. Note that
|
||||
this option is **not yet supported by CMake Tools**.
|
||||
|
|
@ -1,29 +0,0 @@
|
|||
# CMake Cache Editor
|
||||
|
||||
CMake Tools has an experimental GUI for editing your CMake Cache content. It is
|
||||
based on the Qt GUI that comes with the default CMake installation.
|
||||
|
||||
|
||||
|
||||
String cache enties will appear as text edit fields, while boolean cache entries
|
||||
appear as checkboxes. Changes are committed once "Configure" or "Build" is
|
||||
pressed within the cache editor.
|
||||
|
||||
## List Editting
|
||||
|
||||
For strings which contain semicolons `;`, the cache editor will split them
|
||||
into several text fields and stack them on top of eachother in the list
|
||||
ordering. To add a new item to the list, simply use a semicolon in one of the
|
||||
fields, and the cache editor will move it to it's own field after "Configure"
|
||||
is pressed. To remove an entry from a list, simply clear the content from the
|
||||
field that you wish to remove.
|
||||
|
||||
## Missing Features
|
||||
|
||||
The cache editor is still new, and the following features are yet-to-be added,
|
||||
but should be supported in the future:
|
||||
|
||||
- Support for the `STRINGS` property of cache entries (which would make a cache
|
||||
entry a drop-down menu rather than a free text field).
|
||||
- Support for file/path selection/validation.
|
||||
- Adding arbitrary new cache entries.
|
||||
|
|
@ -1,49 +0,0 @@
|
|||
# CMake Tools and CMake Server
|
||||
|
||||
## What is `cmake-server`?
|
||||
|
||||
Version 3.7.0 of CMake introduced `cmake-server`, a mode in which CMake is able
|
||||
to be used as a service such that it can integrate with other tools that wish to
|
||||
obtain information about a CMake project. This is specifically aimed towards
|
||||
development environments and code editors that wish to integrate well with
|
||||
CMake-based projects.
|
||||
|
||||
## CMake Server in Visual Studio Code
|
||||
|
||||
CMake Tools now has support for CMake Server. For the time being, this doesn't
|
||||
have a large effect on the user experience, but it does have a few notable
|
||||
effects:
|
||||
|
||||
- `CMakeToolsHelpers` is no longer necessary for target debugging! Now CMake
|
||||
Tools is able to query CMake directly for information on the project.
|
||||
- More reliable target discovery. Instead of trying to parse the `help` target
|
||||
listing, CMake Tools has 100% accuracy on the list of available targets.
|
||||
- More accurate reconfigure checking. This means that CMake Tools will know with
|
||||
certainty when it must run a reconfigure. No more false positives when
|
||||
reconfiguring.
|
||||
|
||||
## How to Enable CMake Server Support
|
||||
|
||||
To use CMake Server in Visual Studio Code with CMake Tools, the following
|
||||
requirements must be met:
|
||||
|
||||
1. You must be using CMake 3.7.2 or newer. Older 3.7 releases have bugs that
|
||||
severely harm the user experience. Versions prior to CMake 3.7 do not have
|
||||
CMake Server support.
|
||||
2. The configuration setting `cmake.useCMakeServer` must be set to
|
||||
`true` (the default).
|
||||
3. After enabling, Visual Studio Code must be restarted for the changes to take
|
||||
effect.
|
||||
|
||||
Once these things have been done, CMake Tools will use CMake Server to manage
|
||||
your project configuration.
|
||||
|
||||
# Remember!
|
||||
|
||||
CMake Server is still very new and experimental. If you find issues when using
|
||||
CMake Tools with CMake Server, please open a GitHub issue, including relevant
|
||||
information such as CMake version, operating system, and Visual Studio Code
|
||||
version.
|
||||
|
||||
If a bug is inhibitting your workflow, `cmake.useCMakeServer` can
|
||||
be reset back to `false` to disable the CMake Server backend.
|
||||
|
|
@ -1,69 +0,0 @@
|
|||
# Configuration
|
||||
|
||||
CMake tools has a good set of defaults for its configuration options. Here is a
|
||||
quick summary of options that can be tweaked, should you wish to do so:
|
||||
|
||||
- ``cmake.configureSettings`` sets additional options to be passed to the CMake
|
||||
command line when configuring the project. This should just be a mapping between
|
||||
keys and values. Each entry will correspond to a ``-D`` argument to CMake. Arrays
|
||||
will automatically be joined as semicolon-serperated strings.
|
||||
- ``cmake.buildDirectory`` allows you to specify where CMake should generate its
|
||||
metadata and build files. The default, ``${workspaceRoot}/build`` tells CMake
|
||||
Tools to configure into the ``build`` subdirectory of your projet. Use
|
||||
``${buildType}`` to set the build directory based on the CMake build type. For
|
||||
example, ``${workspaceroot}/build/${buildType}`` will create subdirectories
|
||||
``build/Debug``, ``build/Release``, etc. when you configure using those build
|
||||
types.
|
||||
- ``cmake.installPrefix`` tells CMake Tools what to set for your
|
||||
``CMAKE_INSTALL_PREFIX`` when you configure. This also supports variable
|
||||
substitutions. By default, CMake Tools will not specify a
|
||||
``CMAKE_INSTALL_PREFIX``.
|
||||
- ``cmake.parallelJobs`` tells CMake Tools how many jobs to pass to the command
|
||||
line of build tools and CTest. The default, zero, tells CMake Tools to automatically
|
||||
pick a good number based on the hardware parallelism available on the machine.
|
||||
- ``cmake.ctest.parallelJobs`` allows you to override the parallelism _just_ for
|
||||
running CTest. The default, zero, tells CMake Tools to use the same value as
|
||||
``cmake.parallelJobs``.
|
||||
- ``cmake.parseBuildDiagnostics`` enables/disables the parsing of build diagnostics
|
||||
from the compiler. Default is enabled. You may want to disable this if another
|
||||
tool provides live diagnostics.
|
||||
- ``cmake.sourceDirectory`` tells CMake Tools where the root ``CMakeLists.txt``
|
||||
file is. The default is ``${workspaceRoot}``.
|
||||
- ``cmake.saveBeforeBuild`` tells CMake Tools to save all open text documents
|
||||
after the build command is invoked, but before performing the build. This
|
||||
defaults to being _enabled_.
|
||||
- ``cmake.buildBeforeRun`` Always build the target before running.
|
||||
- ``cmake.preferredGenerator`` tells CMake Tools what CMake genertors to prefer.
|
||||
The first supported generator in this list is used when configuring a project
|
||||
for the first time. If a project is already configured, the generator will not
|
||||
be overriden by CMake Tools unless a _Clean rebuild/reconfigure_ is invoked.
|
||||
- ``cmake.generator`` tells CMake to skip the
|
||||
``preferredGenerator`` logic and forcibly use the named generator.
|
||||
- ``cmake.{configure,build,buildTool}Args`` allows passing of arbitrary strings
|
||||
as command line arguments to the respective configure/build step. *Please* do
|
||||
not use this option if another one of CMake Tools' options is sufficient.
|
||||
CMake Tools is better able to integrate with your build system when it can
|
||||
easily understand your project and its settings.
|
||||
- ``cmake.toolset`` tells CMake to set the toolset
|
||||
argument when configuring the first time. (Not to be confused with *toolchain* files!)
|
||||
- ``cmake.platform`` tells CMake to set the platform argument when configuring.
|
||||
- ``cmake.clearOutputBeforeBuild`` clears the _CMake/Build_ output channel before
|
||||
running the CMake build command. Default is _enabled_
|
||||
- ``cmake.cmakePath`` allows you to specify a different CMake executable to use,
|
||||
rather than the default system one.
|
||||
- ``cmake.experimental.enableTargetDebugging`` enables the experimental
|
||||
[Target Debugging](https://github.com/vector-of-bool/vscode-cmake-tools/blob/develop/docs/target_debugging.md)
|
||||
features
|
||||
- ``cmake.debugConfig`` allows tweaking the options for debugging when using
|
||||
the Target Debugging feature.
|
||||
- ``cmake.environment`` sets environment variables to be passed to cmake/build
|
||||
processes invoked by CMake Tools. These can be further refined:
|
||||
- ``cmake.configureEnvironment`` sets environment for CMake configure
|
||||
- ``cmake.buildEnvironment`` sets environment for build execution
|
||||
- ``cmake.testEnvironment`` sets environment variables when running CTest
|
||||
- ``cmake.mingwSearchDirs`` is a list of directories where CMake Tools will
|
||||
search for an installed MinGW environment. A search directory will match if it
|
||||
contains the `bin/`, `include/`, etc. directories with the MinGW binaries,
|
||||
headers, and libraries. There is currently one default search directory,
|
||||
`C:\MinGW`. If more than one directory in this list matches, each matching
|
||||
directory will be an available MinGW environment.
|
||||
|
|
@ -1,157 +0,0 @@
|
|||
# Target Debugging
|
||||
|
||||
Most C and C++ development environments offer some integration with project
|
||||
configuration that requires awareness of the build system, including the
|
||||
presence of targets and build artifacts. The experimental Target Debugging
|
||||
feature offers some such integration with Visual Studio Code for CMake projects
|
||||
that produce executable targets (including executables used just for testing).
|
||||
|
||||
The Target Debugging is meant to make it far simpler for CMake-based projects to
|
||||
manage their debugging setup within VS Code. There is no need to write a
|
||||
``launch.json`` file for Target Debugging, and no need to manually specify
|
||||
the path/architecture/debugger for an executable. All this is determined
|
||||
automatically by CMake Tools when a target-based debug is invoked.
|
||||
|
||||
**NOTE:** CMake Tools extension has enhanced support for using
|
||||
``ms-vscode.cpptools`` is used for debugging C/C++ programs. If you would like
|
||||
to use a different debugger extension, you may use integration with
|
||||
`launch.json` as described below.
|
||||
|
||||
## Selecting a Debug Target
|
||||
Once your project is configured and generated, CMake Tools will automatically
|
||||
discover the project's executables and the paths to which they are written.
|
||||
As executable targets are added to the project, CMake Tools will discover them
|
||||
each time you re-configure the project.
|
||||
|
||||
CMake Tools will automatically (re)build an executables target before it
|
||||
launches the debugger, so there is no need to worry about ensuring the target
|
||||
is built before debugging.
|
||||
|
||||
There are multiple ways of selecting launch target.
|
||||
|
||||
### Using status bar
|
||||
|
||||
Once a CMake project is opened, the following new entries will appear on the
|
||||
status bar:
|
||||
|
||||
|
||||
|
||||
The left-hand button will launch the selected executable target in the debugger.
|
||||
Initially, the text entry may read ``[No target selected for debugging]``. In
|
||||
this case, the project may need to be configured again to generate the metadata.
|
||||
Clicking right-hand button will launch a quick-pick to select a launch target.
|
||||
|
||||
### Using command palette
|
||||
|
||||
Another option is to bring up the Command Palette (``Ctrl+Shift+P`` or `F1`) and
|
||||
select use ``Select a Target to Debug``:
|
||||
|
||||
|
||||
Once target is selected you may also use commands to start it with
|
||||
or without debugging:
|
||||
|
||||
* ``Debug Target``
|
||||
* ``Execute the current target without a debugger``
|
||||
|
||||
## Advanced usage
|
||||
|
||||
### Configuring the debugger
|
||||
|
||||
CMake Tools generates a debugging configuration object on-the-fly when
|
||||
debugging is requested. To set some additional parameters to this debug
|
||||
configuration, use the ``cmake.debugConfig``. Under the hood, CMake Tools
|
||||
delegates to Microsoft's C and C++ extension to do debugging, so all options
|
||||
listed [here](https://github.com/Microsoft/vscode-cpptools/blob/master/launch.md)
|
||||
are available. CMake Tools will fill all required options for you, so you don't
|
||||
need to specify any of the required options outlined in the help document.
|
||||
|
||||
### Running program from ``launch.json``
|
||||
In some cases debugging support provided by CMake Tools may be limited or incorrect.
|
||||
It is possible to use CMake Tools from ``launch.json`` to fill in information
|
||||
about executables and their paths.
|
||||
|
||||
Basic ``launch.json`` configuration may look like this:
|
||||
|
||||
~~~json
|
||||
{
|
||||
"version": "0.2.0",
|
||||
"configurations": [
|
||||
{
|
||||
"name": "Launch CMake-built program",
|
||||
"type": "cppdbg",
|
||||
"request": "launch",
|
||||
"program": "${command:cmake.launchTargetProgramPath}",
|
||||
"stopAtEntry": true,
|
||||
"cwd": "${workspaceRoot}"
|
||||
}
|
||||
]
|
||||
}
|
||||
~~~
|
||||
|
||||
This uses the `${command:...}` syntax to tell VSCode that it should call the
|
||||
named extension command to fill in the respective value.
|
||||
|
||||
In the above example, `program` will be filled out to the path of the active
|
||||
launch target, similar to using the debugging command from CMake Tools.
|
||||
|
||||
A few notes:
|
||||
|
||||
* Use ``"type": "cppvsdbg"`` if you use Visual Studio compiler.
|
||||
* Use ``"program": "${command:cmake.selectLaunchTarget}"`` to pick a new
|
||||
target each time you wish to debug.
|
||||
|
||||
Please refer to VS Code documentation for more information about debugging and
|
||||
`launch.json`
|
||||
|
||||
**NOTE:** If using `launch.json`: due to current limitations of VS Code it is
|
||||
not possible to specify a ``preLaunchTask`` which invokes build via CMake Tools
|
||||
commands, so you must build the desired target before debugging.
|
||||
|
||||
# Enabling Target Debugging for CMake versions < 3.7.2
|
||||
Modern CMake versions provide support for querying information about a project
|
||||
being configured without any modifications to the project itself.
|
||||
|
||||
To achieve this for older versions, CMake Tools will emit a CMake module which
|
||||
can be easily included in any CMake project by adding the following line at the
|
||||
top of the ``CMakeLists.txt`` file, before calling any
|
||||
``add_library`` or ``add_executable``:
|
||||
|
||||
~~~cmake
|
||||
include(CMakeToolsHelpers OPTIONAL)
|
||||
~~~
|
||||
|
||||
The keyword ``OPTIONAL`` here means that CMake won't complain if it fails to
|
||||
find the module. This is very useful, as the script itself isn't important to
|
||||
the build system. As such, this line can be committed to the project and no
|
||||
users will ever have to care about its presence.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Q: CMake isn't finding the `CMakeToolsHelpers` script! Why is this?
|
||||
|
||||
**A:** There are a few primary reasons why CMake might not find it. CMake Tools
|
||||
sets `CMAKE_MODULE_PATH` such that CMake will be able to find the generated
|
||||
helper module. This means that A) CMake will only find this module if it was
|
||||
invoked using CMake Tools within Visual Studio Code and B) destructive
|
||||
modifications of `CMAKE_MODULE_PATH` before the `include` line can cause CMake
|
||||
to not find the module. In the **B** case: *instead* of writing:
|
||||
|
||||
~~~cmake
|
||||
set(CMAKE_MODULE_PATH foo)
|
||||
~~~
|
||||
|
||||
write this:
|
||||
|
||||
~~~cmake
|
||||
list(APPEND CMAKE_MODULE_PATH foo)
|
||||
~~~
|
||||
|
||||
This will append a directory to the module path instead of wiping it out
|
||||
completely.
|
||||
|
||||
### Q: When I `include(CMakeToolsHelpers)`, `add_executable` makes CMake crash!
|
||||
|
||||
**A:** If you run into this issue, you probably know exactly why this happens.
|
||||
This is a known issue with the way CMake provides command hook functionality.
|
||||
Unfortunately, there's no good way to work around it without upgrading to
|
||||
CMake 3.7.2 or newer.
|
||||
Загрузка…
Ссылка в новой задаче