microsoft
/
vscode-cmake-tools
зеркало из https://github.com/microsoft/vscode-cmake-tools.git
1
0
Форкнуть 0
Код Задачи Пакеты Проекты Релизы Вики Активность

Consolidate CMake Tools documentation (#1324)

This commit is contained in:
Tyler Whitney 2020-06-26 15:45:34 -07:00 коммит произвёл GitHub
Родитель b02e5fb3ea
Коммит 28712f5a83
Не найден ключ, соответствующий данной подписи
Идентификатор ключа GPG: 4AEE18F83AFDEB23
47 изменённых файлов: 865 добавлений и 2207 удалений
Показать статистику Скачать Patch файл Скачать Diff файл Показать все файлы Свернуть все файлы

70
docs/README.md
Просмотреть файл

@ -1,5 +1,69 @@
# CMake Tools Documentation
# CMake Tools for Visual Studio Code 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:
CMake Tools is an extension designed to make it easy to work with CMake-based projects.
[Click here to go to the official end-user CMake Tools Documentation](https://vector-of-bool.github.io/docs/vscode-cmake-tools/index.html).
If you are new, try the [CMake Tools quick start](https://code.visualstudio.com/docs/cpp/CMake-linux) and see the [frequently asked questions](faq.md).
[How to](how-to.md)
* [Create a new project](how-to.md#create-a-new-project)
* [Configure a project](how-to.md#configure-a-project)
* [Build a project](how-to.md#build-a-project)
* [Debug a project](how-to.md#debug-a-project)
* [Pass command-line arguments to the debugger](debug-launch.md#debug-using-a-launchjson-file)
* [Set up include paths for C++ IntelliSense](how-to.md#set-up-include-paths-for-c-intellisense)
[Kits](kits.md)
* [How kits are found and defined](kits.md#how-kits-are-found-and-defined)
* [Kit options](kits.md#kit-options)
[Configure](configure.md)
* [CMake configuration process overview](configure.md#cmake-configuration-process-overview)
* [The CMake tools configure step](configure.md#the-cmake-tools-configure-step)
* [The configure step outside of CMake Tools](configure.md#the-configure-step-outside-of-cmake-tools)
* [Clean configure](configure.md#clean-configure)
[Variants](variants.md)
* [Variant YAML example](variants.md#example-yaml-variants-file)
* [Variant schema](variants.md#variant-schema)
* [Variant settings](variants.md#variant-settings)
* [Variant options](variants.md#variant-options)
* [How variants are applied](variants.md#how-variants-are-applied)
* [Large variant file example](variants.md#large-variant-file-example)
[Build](build.md)
* [Build the default target](build.md#build-the-default-target)
* [Build a single target](build.md#build-a-single-target)
* [How CMake tools builds your project](build.md#how-cmake-tools-builds)
* [Clean build](build.md#clean-build)
[Debug and launch](debug-launch.md)
* [Select a launch target](debug-launch.md#select-a-launch-target)
* [Quick debugging](debug-launch.md#quick-debugging)
* [Debug using a launch.json file](debug-launch.md#debug-using-a-launchjson-file)
* [Run without debugging](debug-launch.md#run-without-debugging)
[Configure CMake Tools settings](cmake-settings.md)
* [CMake Tools settings](cmake-settings.md#cmake-settings)
* [Variable substitution](cmake-settings.md#variable-substitution)
[Troubleshoot CMake Tools](troubleshoot.md#troubleshoot-cmake-tools)
* [Common issues and resolutions](troubleshoot.md#common-issues-and-resolutions)
* [CMake Tools is unable to provide IntelliSense configuration](troubleshoot.md#error-cmake-tools-is-unable-to-provide-intellisense-configuration)
* [Green squiggles beneath #include directives](troubleshoot.md#green-squiggles-beneath-include-directives)
* [Debugging ignores launch.json](troubleshoot.md#debugging-ignores-launchjson)
* [Reset CMake Tools extension state](troubleshoot.md#reset-cmake-tools-extension-state)
* [Increase the logging level](troubleshoot.md#increase-the-logging-level)
* [Check the log file](troubleshoot.md#check-the-log-file)
* [Get help](troubleshoot.md#get-help)
[Frequently asked questions](faq.md)
* [How can I get help?](faq.md#how-can-i-get-help)
* [What about CMake language support?](faq.md#what-about-cmake-language-support)
* [How do I learn about CMake?](faq.md#how-do-i-learn-about-cmake)
* [How does CMake Tools work with C and C++ IntelliSense?](faq.md#how-does-cmake-tools-work-with-c-and-c-intellisense)
* [How do I perform common tasks](faq.md#how-do-i-perform-common-tasks)
[How to contribute](contribute.md)
* [Developer Reference](contribute.md#developer-reference)
* [Build the CMake Tools extension](contribute.md#build-the-cmake-tools-extension)
* [Coding guidelines](contribute.md#coding-guidelines)

258
docs/__conf.py
Просмотреть файл

@ -1,258 +0,0 @@
# -*- coding: utf-8 -*-
#
# CMake Tools documentation build configuration file, created by
# sphinx-quickstart on Sat Sep 23 14:46:28 2017.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import sys
import os
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = []
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'CMake Tools'
copyright = u'2017, vector-of-bool'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '1.0.0'
# The full version, including alpha/beta/rc tags.
release = '1.0.0-dev'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = []
# The reST default role (used for this markup: `text`) to use for all
# documents.
#default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
# If true, keep warnings as "system message" paragraphs in the built documents.
#keep_warnings = False
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'default'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
#html_extra_path = []
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}
# If false, no module index is generated.
#html_domain_indices = True
# If false, no index is generated.
#html_use_index = True
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'CMakeToolsdoc'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#'preamble': '',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
('index', 'CMakeTools.tex', u'CMake Tools Documentation',
u'vector-of-bool', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False
# If true, show page references after internal links.
#latex_show_pagerefs = False
# If true, show URL addresses after external links.
#latex_show_urls = False
# Documents to append as an appendix to all manuals.
#latex_appendices = []
# If false, no module index is generated.
#latex_domain_indices = True
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'cmaketools', u'CMake Tools Documentation',
[u'vector-of-bool'], 1)
]
# If true, show URL addresses after external links.
#man_show_urls = False
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
('index', 'CMakeTools', u'CMake Tools Documentation',
u'vector-of-bool', 'CMakeTools', 'One line description of project.',
'Miscellaneous'),
]
# Documents to append as an appendix to all manuals.
#texinfo_appendices = []
# If false, no module index is generated.
#texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#texinfo_show_urls = 'footnote'
# If true, do not generate a @detailmenu in the "Top" node's menu.
#texinfo_no_detailmenu = False

0
docs/_static/dummy.txt поставляемый
Просмотреть файл

55
docs/build.md Normal file
Просмотреть файл

@ -0,0 +1,55 @@
# Build with CMake Tools
Once you have [configured](configure.md) your project, you can run a CMake build. Most of your time with CMake Tools will be spent configuring the build. The build process is much simpler.
You can start a build by:
1. Running **CMake: Build** from the VS Code command pallette.
2. Pressing the keyboard shortcut (the default is `F7`).
3. Selecting the **Build** button in the VS Code status bar.
When the build starts, the CMake Tools output panel opens to display build tool output. The **Build** button will change to a **Stop** button, and may show a progress bar for the running build. Pressing the **Stop** button cancels the running build. Starting a build while another build is running will cancel the current build and start a new one.
> **Note:** The progress bar only displays if the build tool emits output lines that can be parsed to get a percentage of the build progress. This includes Ninja and Makefile generators. MSBuild does not emit this information, so no progress bar will be visible.
The results of the build are written to the directory specified by [cmake.buildDirectory](cmake-settings.md#cmake-settings). This defaults to a subdirectory of the project directory, so the build results are visible within the project explorer. The exact file paths will depend on your CMake project configuration.
## Build the default target
CMake Tools persists a "default target" for the build process. The default target is the "all" target (named `ALL_BUILD` in some generators), which builds all of the targets that CMake has designated for a default build.
The name of the default target is shown in the status bar to the right of the **Build** button in square brackets:
![Default target as shown in the status bar](images/default_target.png)
Selecting this button shows a quick pick list for all the targets CMake Tools is aware of that can be built, along with the full path to the build result that will be generated by the target:
![List of targets](images/target_selector.png)
## Build a single target
You can build a single target without changing the current build target from the VS Code command pallette by running the **CMake: Build a target** command, or by pressing the keyboard shortcut (default is `Shift+F7`). CMake will build any dependent targets, even if they aren't directly selected.
## How CMake Tools builds
### Build flags
CMake Tools builds by passing the `--build` flag to CMake. This flag is used as a generator-agnostic build invocation tool. CMake tools also passes `--config <build-type>`, based on the current build type from the active [variant](variants.md). This instructs multi-configuration build tools which configuration they should build.
For advanced scenarios, additional flags to `--build` can be set with [cmake.buildArgs](cmake-settings.md#cmake-settings), and additional flags for the underlying build tool can be set with [cmake.buildToolArgs](cmake-settings.md#cmake-settings).
### The build environment
Environment variables are inherited from the calling Visual Studio Code process, with additional variables from the [cmake.buildEnvironment](cmake-settings.md#cmake-settings) and [cmake.environment](cmake-settings.md#cmake-settings) settings.
If you are using a [Visual Studio Kit](kits.md#visual-Studio), CMake Tools runs the build with the appropriate environment variables set to build with the chosen version of Visual Studio, much like how it sets these environment variables during [the CMakeTools configure step](configure.md#the-cmake-tools-configure-step).
## Clean build
To clean the build, from the VS Code command pallette run the **CMake: Clean** command. Or run the **CMake: Clean rebuild** command to quickly delete any build results and run the build from scratch.
## Next steps
- Use CMake Tools to [launch and debug](debug-launch.md)
- Learn about [CMake settings](cmake-settings.md#cmake-settings) you can set to control the build.
- Explore the [CMake Tools documentation](README.md)

104
docs/building.rst
Просмотреть файл

@ -1,104 +0,0 @@
.. _building:
CMake Building
##############
Once you have :ref:`configured <configuring>` your project, you can run a CMake
build. Most work with CMake Tools will be done with configuring, and the build
process is much simpler.
Starting a build can be done in one of three ways:
#. Executing the *CMake: Build* command
#. Hitting the associated hotkey (the default being :kbd:`F7`).
#. Pressing the *Build* button in the status bar.
When the build starts, the CMake Tools output panel will be opened and the
output from the build tool will be shown as it runs. The *Build* button will
change to a *Stop* button and may show a progress bar for the running build.
Pressing the *Stop* button will cancel the running build. Attempting to execute
a build while a build is running will cancel the running build and start a new
one.
.. note::
The progress bar will only be shown if the build tool emits output lines
that can be parsed to contain a percentage of the build progress. This
includes Ninja and Makefile generators. MSBuild does not emit this
information, so no progress bar will be visible.
The results of the build will be written to the directory specified by
:ref:`conf-cmake.buildDirectory`. This defaults to a subdirectory of the project
directory, so the build results will be visible within the project explorer.
The exact file paths will depend on the CMake project configuration.
.. _building.default-target:
The Default Target
******************
CMake Tools persists a "default target" for the build process. The default
target is the "all" target (named ``ALL_BUILD`` in some generators), which will
build all targets CMake has designated for a default build.
The name of the default target is shown in the status bar to the right of the
*Build* button in square brackets:
.. image:: res/default_target.png
:align: center
Clicking this button will show a quick-pick for all the target CMake Tools is
aware of that can be built, along with the full path to the build result that
will be generated by the target:
.. image:: res/target_selector.png
:align: center
.. _building.single-target:
Building a Single Target
************************
Instead of changing the build target, one can also request to build a single
target a single time. Run the *CMake: Build a target* command, or hit the
associated hotkey (defaults to :kbd:`Shift+F7`).
.. note::
CMake will build dependent targets, even if they aren't directly selected.
.. _building.how:
How CMake Tools Builds
**********************
Build Flags
===========
CMake Tools builds by passing the ``--build`` flag to CMake. This flag is used
as a generator-agnostic build invocation tool. CMake tools also passes
``--config <build-type>`` based on the current build type from the active
:ref:`variant <variants>`. This instructs multi-conf build tools on what
configuration they should build.
Additional flags to ``--build`` can be set with :ref:`conf-cmake.buildArgs`,
and additional flags for the underlying build tool can be set with
:ref:`conf-cmake.buildToolArgs`. These are advanced options and should only be
used if you know what you are doing.
The Build Environment
=====================
Environment variables will be inherited from the calling Visual Studio Code
process, with additional variables from the :ref:`conf-cmake.buildEnvironment`
and :ref:`conf-cmake.environment` setting.
If using a :ref:`Visual Studio Kit <kits.types.vs>`, CMake Tools runs the build
with the appropriate environment variables set to build with the chosen
Visual Studio, much like how it sets these environment variables when
:ref:`configuring <configuring.how>`.
Cleaning Up
***********
CMake Tools lets you clean the build output by running the *CMake: Clean*
command. One can also run the *CMake: Clean rebuild* to quickly delete build
results and run the build from scratch.

219
docs/changelog.rst
Просмотреть файл

@ -1,219 +0,0 @@
.. _changelog:
Changelog and History
#####################
.. _changes-1.1.3:
1.1.3
*****
Removal:
- The visual CMake cache editor GUI is gone. The API with which it was drawn is
being removed from a future version of VS Code, and the feature had many
issues. A future CMake GUI will be introduced with more features and greater
stability.
(`#579 <https://github.com/vector-of-bool/vscode-cmake-tools/issues/579>`_)
Features and Tweaks:
- On Linux, will detect old CMake versions and offer to do an automatic
upgrade. Windows support is pending. If you have a macOS devices and would
like to contribute, please open a pull request!
- Smarter parsing of GCC and Clang compile errors to fold ``note:`` and
``required from:`` blocks into their main diagnostic. This permits the
folding and browsing of template and macro instantiation errors in a nicer
fashion. MSVC error parsing pending. (**NOTE**: There is an upstream issue
with the sort order of diagnostic information, so ``required from:``
tracebacks may appear out-of-order).
Fixes:
- On Windows, "Launch target in terminal" will use ``cmd.exe`` unconditionally.
This works around issues with command quoting in PowerShell.
(`#562 <https://github.com/vector-of-bool/vscode-cmake-tools/issues/562>`_)
- "Debug target" will prefer ``lldb-mi`` to ``lldb``. Fixes issues where
``cpptools`` is unable to launch the debugger.
(`#584 <https://github.com/vector-of-bool/vscode-cmake-tools/issues/584>`_)
- Document the ``environmentVariables`` field on kits.
(`#586 <https://github.com/vector-of-bool/vscode-cmake-tools/issues/568>`_)
- Fix legacy CMake mode not setting the CMake generator.
(`#567 <https://github.com/vector-of-bool/vscode-cmake-tools/issues/567>`_)
- Permit limited variable expansion for ``cmake.cmakePath`` in ``settings.json``
(refer to documentation for more details).
(`#569 <https://github.com/vector-of-bool/vscode-cmake-tools/issues/569>`_)
.. _changes-1.1.2:
1.1.2
*****
Fixes and tweaks upon 1.1.2:
- Fix silent failure when a build directory appears at a different path than is
encoded in its ``CMakeCache.txt``.
- Improved logic in path normalization, but could be better.
- Improve documentation on using ``launch.json``.
- Fix shell splitting preventing certain command lines from being parsed
correctly.
- Display a more helpful message when using a toolchain file and we fail to find
the C and/or C++ compiler because it is not stored in the CMake cache.
`See the 1.1.2 milestone on GitHub <https://github.com/vector-of-bool/vscode-cmake-tools/milestone/13?closed=1>`_.
.. _changes-1.1.1:
1.1.1
*****
Fixes and tweaks upon 1.1.0:
- Fix "Unable to automatically determine compiler" when using VS generators.
- Fix failure to provide IntelliSense information for header files even after
adding them to a target.
- "Unexpected stderr/stdout..." no longer appears. This output is now logged as
regular CMake status messages.
**BREAKING CHANGE**: Variant substitutions follow a new `${variant:var-key}`
syntax to match the special namespacing of substitutions. See :ref:`variant-sub`.
`See the 1.1.1 milestone on GitHub <https://github.com/vector-of-bool/vscode-cmake-tools/milestone/12?closed=1>`_.
.. _changes-1.1.0:
1.1.0
*****
1.1.0 is the most exciting release yet! It includes several long-awaited
features, including but not limited to:
- *A project outline view*. CMake Tools will now render a tree representation of
your CMake project, including all targets and source files.
- Individual targets can be built/run using the context menu in the outline.
- Individual source files can be compiled using the outline context menu.
- The debugger can be started by right-clicking on the desired executable.
- Update progress and cancellation notifications. Now uses the official VSCode
progress APIs. A proper *Cancel* button is visible on the progress
notification for cancelling the build.
- Progress for the *Configure/Generate* phase. It is up to CMake to generate
reliable progress values, though.
- Automatically configure a project when it is opened. CMake Tools will ask you
the first time, and this preference can be persisted.
- Will automatically ask you for a debug target if you try to debug but haven't
yet set one.
``cpptools`` Integration!
=========================
The highest-demand feature of all has finally landed!
Recent versions of Microsoft's C and C++ extension now export an extensibility
API that gives external sources the opportunity to provide project configuration
information on a file-by-file basis.
CMake Tools 1.1.0+ will utilize this API to provide per-file compilation and
configuration information to support the C++ extension. This means that a
properly set up CMake project need not manually set configuration information
to receive the benefits of cpptools' IntelliSense engine.
Check :ref:`the updated How-Do-I page <hdi.intellisense>`.
.. _changes-1.0.1:
1.0.1
*****
Resolves a few issues/enhancements that didn't make it into 1.0.0.
- Automatically detect when a kit specifies a path to a non-existent compiler
and ask what to do with that kit (remove or keep).
- New option :ref:`conf-cmake.copyCompileCommands`: Set a path to which
``compile_commands.json`` will be copied after a configure run.
- Fix failing when CMake executable has a different name than ``cmake``.
- Fixed edits to the kits file not applying immediately.
- Fixed issue where CTest is not on the ``$PATH`` and it fails to detect tests.
.. _changes-1.0.0:
1.0.0
*****
CMake Tools 1.0.0 is a minor change over 0.11.x, but marks the first "stable"
release. It is now a developer-ready tool that is suitable for everyday work!
[#counter]_
1.0.0 contains the following improvements and fixes over 0.11.x:
- Option to build on ``cmake.launchTargetPath`` (Launch-before-debug).
See :ref:`conf-cmake.buildBeforeRun`.
- `LLVM for Windows <https://llvm.org/builds/>`_ is now supported as an
auto-detected Kit type.
- To support LLVM for Windows, kit options can now be freely mixed-and-matched,
eg. setting a toolchain file along with a Visual Studio environment.
- Cache initialization files are now supported in ``settings.json``. See
:ref:`conf-cmake.cacheInit`.
- Kits are now **optional**. If no kit is active, CMake Tools will ask you if
you want to scan, select a kit, or opt-out of kits. If no kit is chosen, CMake
Tools will let CMake decide what to do.
- GCC cross-compilers are now detected as regular compilers for compiler kits.
- Setting :ref:`conf-cmake.defaultVariants` is respected again.
- Setting :ref:`conf-cmake.mingwSearchDirs` is respected again.
- CMake Tools will attempt to set the path to the debugger (``gdb`` or ``lldb``)
during Quick Debugging.
- Fix for intermittent "Not yet configured" errors.
A few issues slated for 1.0.0 fell through as the schedule slipped. If you
expected a feature in 1.0.0 that isn't listed above, it will be available in
1.0.1.
.. [#counter] If you don't agree, please open a bug report!
.. _changes-0.11.0:
0.11.1
******
Several bugfixes and tweaks:
- Attempted fix for "No build system was generated yet" by implementing more
reliable dirty-checks when running a build/configure.
(`#385 <https://github.com/vector-of-bool/vscode-cmake-tools/issues/385>`_)
- Fix handling spaces in filepaths when running ``vswhere.exe``.
(`#381 <https://github.com/vector-of-bool/vscode-cmake-tools/pull/381>`_)
- Fix environment variables from ``settings.json`` being ignored when using
legacy (non-cmake-server) mode.
(`#384 <https://github.com/vector-of-bool/vscode-cmake-tools/issues/384>`_)
- Do not case-normalize diagnostics on Windows. This prevents VSCode from
considering two equivalent paths to be different when opening them from the
problems panel.
(`#395 <https://github.com/vector-of-bool/vscode-cmake-tools/pull/395>`_)
- Reset progress when build finishes. Stops a flash of "%100" when starting a
new build.
(`#394 <https://github.com/vector-of-bool/vscode-cmake-tools/pull/394>`_)
- Better error message when trying to use debugging on non-cmake-server.
(`#388 <https://github.com/vector-of-bool/vscode-cmake-tools/issues/388>`_)
0.11.0
******
0.11.0 is the biggest change so far to CMake Tools. It brings not just new
functionality, but new infrastructure and maintainers behind the extension.
It began with an `overly-ceremonious blog post <https://vector-of-bool.github.io/2017/12/15/cmt-1.0-and-beta.html>`_,
followed by months of beta (when it should have been a few weeks).
Here's a quick summary:
- :ref:`"Kits" provide a new way to encapsulate the toolset used to build a
project. <kits>`
- Opt-in automatic error reporting.
- Lots of stability and backend cleanup.
- All new documentation!
0.10.x and Older
****************
The old (pre-0.11.0) changelog can be found in `here <https://github.com/vector-of-bool/vscode-cmake-tools/blob/develop/CHANGELOG.pre-0.11.0.md>`_.

69
docs/cmake-settings.md Normal file
Просмотреть файл

@ -0,0 +1,69 @@
# Configure CMake Tools settings
CMake Tools supports a variety of settings that can be set at the user, or workspace, level via VSCode's `settings.json` file. This topic covers the available options and how they are used.
Options that support substitution, in the table below, allow variable references to appear in their strings. See [variable substitution](#variable-substitution), below, for more information about variable expansion.
## CMake settings
|Setting |Description | Default value | Supports substitution |
|---------|---------|---------|-----|
| `cmake.autoSelectActiveFolder`| If 'false', your active folder only changes if you manually run the `CMake: Select Active Folder` command. | 'true' | no |
| `cmake.buildArgs` | An array of additional arguments to pass to `cmake --build`. | `[]` (empty array-no additional arguments) | yes |
| `cmake.buildBeforeRun` | If `true`, build the launch/debug target before running the target. | `true` | no |
| `cmake.buildDirectory` | Specify the build directory (i.e. the root directory where `CMakeCache.txt` will be generated.) | `${workspaceFolder}/build` | yes |
| `cmake.buildEnvironment`| An object containing `key:value` pairs of environment variables, which will be passed only to the compiler. | `null` (no environment variables specified) | yes |
| `cmake.buildToolArgs` | An array of additional arguments to pass to the underlying build tool. | `[]` (empty array-no additional arguments) | yes |
| `cmake.cacheInit` | Path, or list of paths, to cache-initialization files. Passed to CMake via the `-C` command-line argument. | `[]` (empty array-no cache initializer files) | no |
| `cmake.cmakePath`| Specify location of the cmake executable. | `cmake` (causes CMake Tools to search the `PATH` environment variable, as well as some hard-coded locations.) | Supports substitution for `workspaceRoot`, `workspaceFolder`, `workspaceRootFolderName`, `userHome`, `${command:...}` and `${env:...}`. Other substitutions result in an empty string. |
| `cmake.cmakeCommunicationMode` | Specifies the protocol for communicating between the extension and CMake | `automatic` | no |
| `cmake.configureArgs` | Arguments to CMake that will be passed during the configure process. Prefer to use `cmake.configureSettings` or [CMake variants](variants.md).</br> Do not pass `-D` arguments using this setting. | `[]` (empty array-no arguments) | yes |
| `cmake.configureEnvironment` | An object containing `key:value` pairs of environment variables, which will be passed to CMake only when configuring.| `null` (no environment variable pairs) | yes |
| `cmake.configureSettings` | An object containing `key:value` pairs, which will be passed to CMake when configuring. The same as passing `-DVAR_NAME=ON` via `cmake.configureArgs`. | `null` (no values) | yes |
| `cmake.copyCompileCommands`| If not `null`, copies the `compile_commands.json` file generated by CMake to the path specified by this setting whenever CMake successfully configures. | `null` (do not copy the file) | yes |
| `cmake.defaultVariants` | Override the default set of variants that will be supplied when no variants file is present. See [CMake variants](variants.md). | | no |
| `cmake.environment` | An object containing `key:value` pairs of environment variables, which will be passed onto CMake when configuring and to the compiler. | `null` (no environment variables) | yes |
| `cmake.generator` | Set to a string to override CMake Tools preferred generator logic. If set, CMake will unconditionally use it as the `-G` CMake generator command line argument. ||no|
| `cmake.installPrefix` | If specified, sets a value for `CMAKE_INSTALL_PREFIX` when running CMake configure. If not set, no value will be passed.</br>If `CMAKE_INSTALL_PREFIX` is set via `cmake.configureArgs` or `cmake.configureSettings`, `cmake.installPrefix` will be ignored.| `null` (no value specified) | yes |
| `cmake.loggingLevel` | A string setting that specifies how much output CMake Tools produces in its output channel. Set to one of `"trace"`, `"debug"`, `"info"`, `"note"`, `"warning"`, `"error"`, or `"fatal"`. `"trace"` is the most verbose.</br></br>Regardless of the logging level, CMake Tools writes all levels of logging to the CMake Tools log file. This file is useful if you need to [troubleshoot CMake Tools](troubleshoot.md) | `"info"` | no |
| `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. | ["C:\\MinGW"] (Search in C:\MinGW for a MinGW installation) | no |
| `cmake.parallelJobs` | Specify the number of jobs run in parallel during the build. | | no |
| `cmake.preferredGenerators` | A list of strings of generator names to try, in order, when configuring a CMake project for the first time. | | no |
| `cmake.saveBeforeBuild` | If `true` (the default), saves open text documents when build or configure is invoked before running CMake. | `true` | no |
| `cmake.sourceDirectory` | Directory where the root `CMakeLists.txt` is stored. | `${workspaceFolder}` | yes |
## Variable substitution
Some options support the replacement of special values in their string value by using a `${variable}` syntax. The following built-in variables are expanded:
| Variable | Expansion |
|---------|---------|
|`${workspaceRoot}`|**DEPRECATED**. The full path to the workspace root directory.|
|`${workspaceFolder}` | The full path to the workspace root directory. |
|`${workspaceRootFolderName}`| The name of the leaf directory in the workspace directory path.|
|`${buildType}`|The current CMake build type. For example: `Debug`, `Release`, `MinSizeRel`|
|`${buildKit}`| The current CMake kit name. For example: `GCC 7.3.0`|
|`${generator}`| The name of the CMake generator. For example: `Ninja`|
|`${projectName}`|**DEPRECATED**. Expands to the constant string `"ProjectName"` CMake does not consider there to be just one project name to use. The concept of a single project does not work in CMake. Use `${workspaceRootFolderName}`, instead.|
|`${userHome}`| The full path to the current user's home directory. |
### Environment variables
Environment variables are expanded using the `${env:VARNAME}` and `${env.VARNAME}` syntax, where `VARNAME` is the environment to variable to expand. If the named environment variable is undefined, the expansion is an empty string.
### Variant substitution
Variant options are expanded using the `${variant:VARIANTNAME}` syntax, where the name of the currently active choice of the provided `VARIANTNAME` variant option is expanded. If the variant option is undefined, the expansion is an empty string.
### Command substitution
CMake Tools can expand VS Code commands. for example, you can expand the path to the launch target by using the syntax `${command:cmake.launchTargetPath}`
Be careful with long-running commands because it isn't specified when, or how many times, CMake Tools will execute a command for a given expansion.
## Next steps
- Learn about [user vs. workspace settings](https://code.visualstudio.com/docs/getstarted/settings)
- [Get started with CMake Tools on Linux](https://code.visualstudio.com/docs/cpp/cmake-linux)
- Review [How CMake Tools builds](build.md#how-cmake-tools-builds)
- Explore the [CMake Tools documentation](README.md)

58
docs/common_issues.rst
Просмотреть файл

@ -1,58 +0,0 @@
.. _common-issues:
Common Issues and Resolutions
#############################
There are a few frequently appearing issues in the CMake Tools issue tracker.
Make sure you've checked that your issue isn't already solved here before
submitting a question or bug report.
.. _missing-config:
I see: 'CMake Tools' is unable to provide IntelliSense configuration ...
************************************************************************
If you are seeing this informational pop-up appear, or are seeing that
``#include`` directives are not resolving in the editor (you see a green
underline on the ``#include`` directive), this means that the relevant source
file is not attached to a CMake Target.
.. note::
The target of a failing ``#include`` directive **need not** be a source
file of your target. This is only concerning the file *containing* the
failing ``#include`` directive!
If the file which receives this message is outside of your project, it is safe
to ignore it.
If you are receiving this message for files *within* your project, it means you
probably need to add the source file to a target.
This is most common with header files in a project. **Header files should be
included in the source list of a target**. Even though CMake will not try to
compile or process these headers in any special way, CMake Tools uses this
information in a variety of places to provide a better user experience.
.. _failing-include:
I see green underlines/squiggles beneath my ``#include`` directives in my source files
**************************************************************************************
.. note::
Please refer to :ref:`missing-config`
.. _debug-button-no-launch:
The "Debug" button and "Debug target" features are ignoring my ``launch.json``
******************************************************************************
If you wish to specify additional debugging options, and/or use a different
debugging engine, refer to :ref:`debugging.launch-json`.
.. note::
The target debugging feature is restricted to launching target executables
with a default configuration in cpptools' debugging engine.

100
docs/configure.md Normal file
Просмотреть файл

@ -0,0 +1,100 @@
# The CMake configure process
In CMake, _configure_ refers to detecting requirements and generating the build files that will produce the final compiled artifacts.
The following concepts will help you understand how CMake Tools interacts with CMake's configure process:
* The _CMake Cache_ is a list of key-value pairs that persist between runs of the configure process. It contains the following:
* Values that are expensive to determine, such as whether a `-flag` or `#include` file is supported by the compiler.
* Values that rarely change, such as the path to a header/library.
* Values that offer control to the developer, such as `BUILD_TESTING` to determine whether or not to build test libraries/executables.
* _Cache initializer arguments_ are the arguments passed to CMake that set values in the cache before any CMake scripts are run. These allow you to control the build settings. On the CMake command line, these appear as `-D` arguments. (CMake Tools doesn't use CMake's `-C` argument).
* Unless overwritten or deleted, values in the CMake Cache persist between CMake runs.
* CMake doesn't do the build itself, it relies on build tools installed on your system. The result of a _configure_ depends on the CMake _Generator_. The _Generator_ tells CMake what kind of tool will be used to compile and generate the results of the build. There are several families of generators available:
|Generator |Description|
|---------|---------|
|Ninja | Emits files for the [Ninja build tool](https://ninja-build.org). This is the generator CMake Tools tries first, unless configured otherwise. See [cmake.preferredGenerators](cmake-settings.md#cmake-settings). |
|Makefile | Emits a `Makefile` for the project that can be built via `make`.|
|Visual Studio | Emits visual studio solutions and project files. There are many different Visual Studio generators, so it is recommended to let CMake Tools automatically determine the appropriate generator.|
Regardless of generator, CMake Tools always supports building from within Visual Studio Code. If you are building from within Visual Studio Code, we recommend you use the [Ninja build tool](https://ninja-build.org/).
## The CMake Tools configure step
CMake Tools drives CMake via the cmake-file-api which provides project info via a file on disk.
When CMake Tools runs the configure step, it takes the following into consideration:
1. **The active kit**
[CMake kits](kits.md) provide information about the toolchains available on your system that can be used with CMake to build your projects.
* For [toolchain](kits.md#specify-a-toolchain), CMake Tools sets the CMake cache variable `CMAKE_TOOLCHAIN_FILE` to the path to the file specified by the kit.
* For [compilers](kits.md#specify-a-compiler), CMake Tools sets the `CMAKE_<LANG>_COMPILER` cache variable to point to the path for each `<LANG>` defined in the kit.
* For [Visual Studio](kits.md#visual-studio), CMake Tools sets environment variables necessary to use the selected Visual Studio installation, and sets `CC` and `CXX` to `cl.exe` so that CMake will detect the Visual C++ compiler as the primary compiler, even if other compilers like GCC are present on `$Path`.
Each kit may also define additional cache variable settings required for the kit to operate. A kit may also define a `preferredGenerator`.
See [CMake kits](kits.md) for more information about how kits work.\
See [Kit options](kits.md#kit-options) for more information about the different types of kits.
1. **Which generator to use**
CMake Tools tries not to let CMake decide implicitly which generator to use. Instead, it tries to detect a preferred generator from a variety of sources, stopping when it finds a valid generator. The sources it checks are:
1. The config setting [cmake.generator](cmake-settings.md#cmake-settings).
1. The config setting [cmake.preferredGenerators](cmake-settings.md#cmake-settings). Each element in this list is checked for validity, and if one matches, it is chosen. The list has a reasonable default that works for most environments.
1. The kit's [preferredGenerator](cmake-settings.md#cmake-settings) attribute. Automatically generated Visual Studio kits set this attribute to the Visual Studio generator matching their version.
1. If no generator is found, CMake Tools produces an error.
1. **The configuration options**
CMake Tools has a variety of locations where configuration options can be defined. They are searched in order and merged together. When keys have the same name, the most recent value found during the search is used. The search locations are:
1. The [cmake.configureSettings](cmake-settings.md#cmake-settings) option from `settings.json`.
2. The `settings` value from the active [variant options](variants.md#variants-options).
3. `BUILD_SHARED_LIBS` is set based on [variant options](variants.md#variants-options).
4. `CMAKE_BUILD_TYPE` is set based on [variant options](variants.md#variants-options).
5. `CMAKE_INSTALL_PREFIX` is set based on [cmake.installPrefix](cmake-settings.md#cmake-settings).
6. `CMAKE_TOOLCHAIN_FILE` is set for [toolchain](kits.md#specify-a-toolchain).
7. The [cmakeSettings](kits.md#generic-options) attribute on the active kit.
Additionally, [cmake.configureArgs](cmake-settings.md#cmake-settings) are passed before any of the above.
1. **The configure environment**
CMake Tools sets environment variables for the child process it runs for CMake. Like the configuration options, values are merged from different sources, with later sources taking precedence. The sources are:
1. The environment variables required by the active [kit](kits.md).
2. The value of [cmake.environment](cmake-settings.md#cmake-settings).
3. The value of [cmake.configureEnvironment](cmake-settings.md#cmake-settings).
4. The environment variables required by the active [variant](variants.md).
All of the above are taken into account to perform the configure. Once finished, CMake Tools loads project information from CMake and generates diagnostics based on CMake's output. You are now ready to [build with CMake Tools](build.md).
## The configure step outside of CMake Tools
CMake Tools is designed to work well with an external CMake process. If you choose to run CMake from another command line, or other IDE/tool, it should work provided the host environment is set up properly.
> **Important:**
> CMake Tools is unaware of any changes made by an external CMake process, and you will need to re-run the CMake configure within CMake Tools to have up-to-date project information.
## Clean configure
To get CMake Tools to do a clean configure, run **CMake: Delete cached built settings and reconfigure** from the command palette in VS Code.
A clean configure deletes the `CMakeCache.txt` file and `CMakeFiles` directory from the build directory. This resets all of CMake's default state.
A clean configure is required for certain build system changes, such as when the active kit changes, but may als be convenient as a reset if you have changed configuration settings outside of CMake Tools.
CMake Tools will do a clean configure automatically if you change the active kit.
## Next steps
- Explore how to build at [Build with CMake Tools](build.md)
- Learn how kits work at [CMake Kits](kits.md)
- Explore the [CMake Tools documentation](README.md)

169
docs/configuring.rst
Просмотреть файл

@ -1,169 +0,0 @@
.. _configuring:
CMake Configuring
#################
CMake Tools wraps the CMake *configure* process separately from the *build*
process.
.. seealso::
- :ref:`getting-started`
A Crash-Course on CMake's Configuration Process
***********************************************
For those new to CMake, *Configure* refers to the process of detecting
requirements and generating the build files that will produce the final
compiled artifacts.
To understand how CMake Tools interacts with CMake's configure process, a few
things must be discussed:
- The *CMake Cache* is a list of key-value pairs that persist between
executions of the configure process. It contains a few different types of
values:
- Values that are often heavy or slow to compute, such as whether a ``-flag``
or ``#include`` file is supported by the compiler.
- Values that rarely change, such as the path to a header/library.
- Values that offer control to the developer, such as ``BUILD_TESTING``
to determine whether or not to build test libraries/executables.
- *Cache initializer arguments* are the arguments passed to CMake that set
values in the cache before any CMake scripts are executed. This lets one
control build settings. On the CMake command line, these appear as ``-D``
arguments [#cache-init]_.
- Unless overwritten or deleted, values in the CMake Cache will persist between
executions of CMake.
- The result of a *configure* depends on the CMake *Generator*. The *Generator*
tells CMake what kind of tool will be used to compile and generate the results
of the build, since CMake doesn't do the build itself. There are several
families of generators available:
- *Ninja* - Emits files for the `Ninja build tool <https://ninja-build.org/>`_.
This is the generator CMake Tools will always try first, unless configured
otherwise. (See :ref:`conf-cmake.preferredGenerators`).
- *Makefile* - Emits a ``Makefile`` for the project that can be built via
``make``.
- *Visual Studio* - Emits visual studio solutions and project files. There are
many different Visual Studio generators, so it is recommended to let CMake
Tools automatically determine the appropriate generator.
Regardless of generator, CMake Tools will always support building from within
Visual Studio Code. Choosing a particular generator is unimportant
[#use-ninja]_.
.. Check if this still applies in the future:
.. [#cache-init]
CMake also supports a ``-C`` argument, but this isn't used by or
configurable from CMake Tools.
.. [#use-ninja]
But you should use `Ninja <https://ninja-build.org/>`_.
.. _configuring.how:
How CMake Tools Configures
**************************
CMake Tools speaks to CMake over *CMake Server*, an execution mode of CMake
wherein a persistent connection is held open to query information and get
project information.
When CMake Tools runs the configure step, it takes a few things into
consideration to run the configuration:
#. *The active kit* - :ref:`CMake Tools' Kits <kits>` tell CMake Tools about the
toolchains available on your system that can be used with CMake to build
your projects.
- For :ref:`kits.types.toolchain`, CMake Tools sets the CMake cache variable
``CMAKE_TOOLCHAIN_FILE`` to the path to the file specified by the kit.
- For :ref:`kits.types.compiler`, CMake Tools sets the ``CMAKE_<LANG>_COMPILER``
cache variable to point to the path for each ``<LANG>`` defined in the
kit.
- For :ref:`kits.types.vs`, CMake Tools starts the CMake Server process with the
environment variables necessary to use the selected Visual Studio
installation. It also sets ``CC`` and ``CXX`` to ``cl.exe`` to force
CMake to detect the Visual C++ compiler as the primary compiler, even if
other compilers like GCC are present on the ``$PATH``.
Each kit may also define additional cache variable settings requires for the
kit to operate. A kit may also define a ``preferredGenerator``.
.. seealso::
- :ref:`kits` - Describes how Kits work
- :ref:`kits.types` - The different types of kits
#. *The generator to use* - CMake Tools tries not to let CMake decide implicitly
on which generator to use. Instead it tries to detect a "preferred" generator
from a variety of sources, stopping when it finds a valid generator:
#. The config setting :ref:`conf-cmake.generator`.
#. The config setting :ref:`conf-cmake.preferredGenerators` - Each element
in this list is checked for validity, and if one matches, it is chosen.
The list has a reasonable default that will work for most environments.
#. The kit's :ref:`preferredGenerator <kits.common.preferredGenerator>`
attribute. Automatically generated Visual Studio kits will set this
attribute to the Visual Studio generator matching their version.
#. If no generator is found, CMake Tools produces an error.
#. *The configuration options* - CMake Tools has a variety of locations where
configuration options can be defined. They are searched in order and merged
together, with later searches taking precedence in case of overlapping keys:
#. The :ref:`conf-cmake.configureSettings` option from ``settings.json``.
#. The ``settings`` value from the active :ref:`variants.opts`.
#. ``BUILD_SHARED_LIBS`` is set based on :ref:`variants.opts`.
#. ``CMAKE_BUILD_TYPE`` is set based on :ref:`variants.opts`.
#. ``CMAKE_INSTALL_PREFIX`` is set based on :ref:`conf-cmake.installPrefix`.
#. ``CMAKE_TOOLCHAIN_FILE`` is set for :ref:`kits.types.toolchain`.
#. The :ref:`cmakeSettings <kits.common.cmakeSettings>` attribute on the
active kit.
Additionally, :ref:`conf-cmake.configureArgs` are passed *before* any of
the above.
#. *The configure environment* - CMake Tools sets environment variables for the
child process it runs for CMake. Like the configuration options, values are
merged from different sources, with later sources taking precedence:
#. The environment variables required by the active :ref:`kit <kits>`.
#. The value of :ref:`conf-cmake.environment`.
#. The value of :ref:`conf-cmake.configureEnvironment`.
#. The environment variables required by the active :ref:`variant <variants>`.
All of the above are taken into account to perform the configure. Once finished,
CMake Tools will load project information from CMake and generate diagnostics
based on CMake's output. :ref:`You are now ready to build! <building>`
Configuring Outside of CMake Tools
**********************************
CMake Tools is built to play nicely with an external CMake process. If you
choose to run CMake from another command line or other IDE/tool, all should
work successfully (provided the host environment is set up properly).
Nevertheless, be aware: CMake Tools will be unaware of any changes made by an
external CMake process, and you will need to re-run the CMake configure within
CMake Tools to have up-to-date project information.
A "Clean" Configure
*******************
CMake Tools also has the concept of a "clean configure," executed by running
*CMake: Delete cached built settings and reconfigure*. The process consists
simply of deleting the ``CMakeCache.txt`` file and ``CMakeFiles`` directory
from the build directory. This is enough to reset all of CMake's default state.
Should additional cleaning be necessary, it must be done by hand.
This process is required for certain build system changes, but may be convenient
as a "reset" if you have tweaked any configuration settings outside of CMake
Tools.
CMake Tools will also do this *automatically* if you change the active
:ref:`kit <kits>`. CMake can't yet properly handle changing the toolchain
without deleting the configuration data.

49
docs/contribute.md Normal file
Просмотреть файл

@ -0,0 +1,49 @@
# How to Contribute to CMake Tools
This article is for developers who want to contribute to the CMake Tools open source project.
## Developer Reference
Documentation for the code is kept within the code, and is extracted via `TypeDoc`.
## Build the CMake Tools extension
As with most VS Code extensions, you'll need `Node.JS <https://nodejs.org/en/>` installed.
The process is:
1. Install dependencies
```bash
$ npm install
```
1. Compile the code:
```bash
$ npm install
```
## Coding guidelines
### Formatting
Code is formatted using `clang-format`. We recommend you install the
[Clang-Format extension](https://marketplace.visualstudio.com/items?itemName=xaver.clang-format).
### Linting
We use tslint for linting our sources.
You can run `tslint` across the sources from a terminal or command prompt by running `npm run lint`.
You can also run `npm: lint` from the VS Code command pallette ry running the `task lint` command.
Warnings from `tslint` show up in the **Errors and Warnings** pane and you can navigate to them from inside VS Code.
To lint the source as you make changes, install the [tslint extension](https://marketplace.visualstudio.com/items/eg2.tslint).
### Style
* Use inline field initializers whenever possible.
* Declare properties in constructor parameters lists, when possible.
* Use `lowerCamelCase` for public members, methods, and function/method parameters.
* Use `snake_case` for variables.
* Use `kebab-case` (hyphen-separated-names) for files and directories.
* Prefix private members/methods with an underscore and write them `_withCamelCase`.

97
docs/debug-launch.md Normal file
Просмотреть файл

@ -0,0 +1,97 @@
# CMake: Debug and launch
CMake Tools makes it easier to set up debugging. Because C and C++ projects may define multiple (sometimes dozens or even hundreds) of executables, creating a `launch.json` may be difficult.
If you define any executable targets via CMake, CMake Tools will be aware of them and allow you to start debugging them.
> **Note:**
> Debugging is supported when CMake is using either _CMake Server_ or the cmake-file-api. These modes are enabled automatically for CMake versions 3.7.2 and above. Debugging is not available on older versions.
If you are running an older version of CMake and want to use target debugging, update your CMake version to version 3.7.2 or higher.
By default, launching or debugging an executable target causes it to be built first. This can be disabled with the [cmake.buildBeforeRun](cmake-settings.md#cmake-settings) setting.
## Select a launch target
The first time you run target debugging, CMake Tools asks for you to specify a target, which will be persisted between sessions.
The active launch target is shown in the status bar to the right of the *Debug* button:
![Image of launch target to the right of the debug button](images/launch_target.png)
Selecting the active launch target button will show the launch target selector so that you can change the active launch target.
## Quick debugging
Quick-debugging lets you start a debugger on a target without creating a `launch.json`.
> **Note:**
> Only the debugger from Microsoft's `vscode-ms-vscode.cpptools` extension supports quick-debugging. See [Debug using a launch.json file](#debug-using-a-launchjson-file), below, for information about `launch.json` and using other debuggers.
Start quick debugging by running the *CMake: Debug Target* command from the VS Code command pallette, or by pressing the keyboard shortcut (the default is **Ctrl+F5**).
> **Note:**
> Quick-debugging does not let you specify program arguments or other debugging options. See the next section for more options.
## Debug using a launch.json file
You can specify the working directory or command line arguments for debugging, or use another debugger than the one included with Microsoft's `vscode-ms-vscode.cpptools`, by creating a `launch.json` file.
You'll need to know the path to the executable binary, which may be difficult to know in advance. CMake Tools can help by using command substitution in the `launch.json` file. This is already used by things like process selection when attaching to a running process. It works by specifying a command-based substitution in the appropriate field of `launch.json`.
Here is a minimal example of a `launch.json` file that uses `cmake.launchTargetPath` and `cmake.launchTargetDirectory` to start a debugger on the active launch target:
```json
{
"version": "0.2.0",
"configurations": [
{
"name": "(gdb) Launch",
"type": "cppdbg",
"request": "launch",
// Resolved by CMake Tools:
"program": "${command:cmake.launchTargetPath}",
"args": [],
"stopAtEntry": false,
"cwd": "${workspaceFolder}",
"environment": [
{
// add the directory where our target was built to the PATHs
// it gets resolved by CMake Tools:
"name": "PATH",
"value": "$PATH:${command:cmake.launchTargetDirectory}"
},
{
"name": "OTHER_VALUE",
"value": "Something something"
}
],
"externalConsole": true,
"MIMode": "gdb",
"setupCommands": [
{
"description": "Enable pretty-printing for gdb",
"text": "-enable-pretty-printing",
"ignoreFailures": true
}
]
}
]
}
```
The value of the `program` attribute is expanded by CMake Tools to be the absolute path of the program to run.
> **Note:**
> You must successfully [configure](configure.md) before `cmake.launchTargetPath` and `cmake.launchTargetDirectory` will resolve correctly.
## Run without debugging
If you want to run a target without debugging it, from VS Code's command pallette, run the *CMake: Execute the current target without a debugger* command, or by pressing the keyboard shortcut (the default `Shift+F5`).
The output of the target will be shown in an integrated terminal.
## Next steps
- See how to [troubleshoot CMake Tools](troubleshoot.md)
- Explore the [CMake Tools documentation](README.md)

141
docs/debugging.rst
Просмотреть файл

@ -1,141 +0,0 @@
.. _debugging:
Target Debugging and Launching
##############################
CMake Tools removes some of the friction required in setting up debugging.
Because C and C++ projects may define multiple (sometimes dozens or even
hundreds) of executables, creating a ``launch.json`` may be difficult, tedious,
and error-prone.
If you define any executable targets via CMake, CMake Tools will be aware of
them and allow you to start a debugger on them.
.. note::
Debugging is only supported when using *CMake Server* mode. This mode will
be enabled automatically on CMake versions at least as new as 3.7.2, but is
completely unavailable on older CMake versions.
Target debugging used to be supported on prior versions, but was difficult
and error-prone, creating more problems than it solved. If you are running
an older CMake version and wish to use target debugging, you'll have to
update your CMake version.
By default, the launch or debug of an executable target will cause it to be
built.
.. note::
The build on launch can be disabled with a setting, see
:ref:`conf-cmake.buildBeforeRun`.
Selecting a Launch Target
*************************
The "launch target" or "debug target" is initially unset. The first time you try
to run target debugging, CMake Tools will ask you to specify a target, which
will be persisted between sessions.
The active launch target is shown in the status bar to the right of the *Debug*
button:
.. image:: res/launch_target.png
:align: center
Pressing this button will show the launch target selector and lets one change
the active launch target.
Quick Debugging
***************
Quick-debugging lets you start a debugger on a target without ever creating
a ``launch.json``.
.. note::
At the moment, only the debugger from Microsoft's ``vscode-cpptools``
extension is supported with quick-debugging. See :ref:`debugging.launch-json`
below for using ``launch.json`` and other debuggers.
Quick debugging can be started using the *CMake: Debug Target* command from
the command pallette, or by pressing the associated hotkey (the default is
:kbd:`Ctrl+F5`).
.. note::
Quick-debugging does not let you specify program arguments or other
debugging options. See :ref:`debugging.launch-json` for more options.
.. _debugging.launch-json:
Debugging with CMake Tools and ``launch.json``
**********************************************
Sometimes, more flexibility is needed for debugging, including setting things
like the working directory or command line arguments. In addition, one may want
to use a debugger other than the one included with Microsoft's
``vscode-cpptools``.
All these things can be done using ``launch.json``. The primary obstacle to
using ``launch.json`` is that the path to the executable binary might be
difficult to know in advance. CMake Tools can help by using
*Command substitution* in ``launch.json``. This is already used by things like
the process selection when attaching to a running process. It works by simply
specifying a a command-based substitution in the appropriate field of
``launch.json``.
Here is a minimal example of a ``launch.json`` that uses the
``cmake.launchTargetPath`` and ``cmake.launchTargetDirectory`` to start a debugger
on the active selected launch target:
.. code:: javascript
{
"version": "0.2.0",
"configurations": [
{
"name": "(gdb) Launch",
"type": "cppdbg",
"request": "launch",
// Resolved by CMake Tools:
"program": "${command:cmake.launchTargetPath}",
"args": [],
"stopAtEntry": false,
"cwd": "${workspaceFolder}",
"environment": [
{
// add the directory where our target was built to the PATHs
// it gets resolved by CMake Tools:
"name": "PATH",
"value": "$PATH:${command:cmake.launchTargetDirectory}"
},
{
"name": "OTHER_VALUE",
"value": "Something something"
}
],
"externalConsole": true,
"MIMode": "gdb",
"setupCommands": [
{
"description": "Enable pretty-printing for gdb",
"text": "-enable-pretty-printing",
"ignoreFailures": true
}
]
}
]
}
The value of the ``program`` attribute is resolved by CMake Tools to the
absolute path to the program to run.
.. note::
A successful :ref:`configure <configuring>` must be executed before
``cmake.launchTargetPath`` and ``cmake.launchTargetDirectory`` will resolve correctly.
Running Targets Without a Debugger
**********************************
Sometimes one will want to just run a target and see its output. This can
be done with the *CMake: Execute the current target without a debugger* command,
or the associated keybinding (the default is :kbd:`Shift+F5`).
The output of the target will be shown in an integrated terminal.

54
docs/development.rst
Просмотреть файл

@ -1,54 +0,0 @@
How to Contribute
=================
Developer Reference
-------------------
Documentation for the code itself is kept within the code, and is extracted via
TypeDoc. See the developer reference documentation `here <dev/index.html>`_.
Building extension
------------------
As with most VS Code extensions you need you need `Node.JS <https://nodejs.org/en/>`_ installed.
The process if fairly straightforward:
1. Install dependencies
.. code:: bash
$ npm install
2. Compile the code:
.. code:: bash
$ npm run compile
Of course build command (as few others) is available as Visual Studio Code task.
Coding guidelines
-----------------
Formatting
::::::::::
Code is formatted using ``clang-format``. It is recommended to install
`Clang-Format extension <https://marketplace.visualstudio.com/items?itemName=xaver.clang-format>`_.
Linting
:::::::
We use tslint for linting our sources.
You can run tslint across the sources by calling ``npm run lint`` from a terminal or command prompt.
You can also run ``npm: lint`` as a Code task by pressing ``CMD+P`` (``CTRL+P`` on Windows) and entering ``task lint``.
Warnings from tslint show up in the Errors and Warnings quick box and you can navigate to them from inside Code.
To lint the source as you make changes you can install the `tslint extension <https://marketplace.visualstudio.com/items/eg2.tslint>`_.
Style
:::::
* Use inline field initializers whenever possible.
* Declare properties in constructor parameters lists, when possible.
* Use ``lowerCamelCase`` for public members, methods, and function/method parameters.
* Use ``snake_case`` for variables.
* Use ``kebab-case`` for files and directories. (hyphen-separated-names)
* Prefix private members/methods with an underscore and write them ``_withCamelCase``

29
docs/faq.md Normal file
Просмотреть файл

@ -0,0 +1,29 @@
# Frequently asked questions — CMake Tools 1.4.0 documentation
## How can I get help?
Please visit [the end-user support chat](https://gitter.im/vscode-cmake-tools/support). This is a community chat. Microsoft does not actively monitor it.
Also look in the [Troubleshooting guide](troubleshoot.md).
Check the [CMake Tools issue tracker](https://github.com/vector-of-bool/vscode-cmake-tools/issues) and [What's New](https://github.com/microsoft/vscode-cmake-tools/blob/develop/CHANGELOG.md) to see if your issue is already known/solved before submitting a question or bug report. Feel free to [Open a Github issue](https://github.com/microsoft/vscode-cmake-tools/issues) if your problem hasn't been reported.
Explore the [CMake Tools documentation](README.md)
## What about CMake language support?
CMake Tools was created separately from the [CMake extension](https://marketplace.visualstudio.com/items?itemName=twxs.cmake), which provides language coloring and autocompletion support.
## How do I learn about CMake?
CMake Tools is not the same as CMake. There are many great resources around to learn how to use CMake. See Jason Turner's [C++ Weekly - Intro to CMake](https://www.youtube.com/watch?v=HPMvU64RUTY) for a good video introduction.
[CMake's documentation](https://marketplace.visualstudio.com/items?itemName=twxs.cmake) is also available.
## How does CMake Tools work with C and C++ IntelliSense?
See [Pass command-line arguments to the debugger](how-to.md#pass-command-line-arguments-to-the-debugger)
## How do I perform common tasks
See the [How To](how-to.md).

47
docs/faq.rst
Просмотреть файл

@ -1,47 +0,0 @@
.. _faq:
Frequently Asked Questions
##########################
How Can I Get Help?
*******************
CMake Tools is a volunteer-run project. You can ask around for help in the
`end-user support Gitter chat <https://gitter.im/vscode-cmake-tools/support>`_.
Also look in the :ref:`troubleshooting guide <troubleshooting>`. You can always
open a `GitHub issue <https://github.com/vector-of-bool/vscode-cmake-tools/issues>`_
if all else fails.
What About CMake Language Support?
**********************************
CMake Tools was create separately from the `CMake extension
<https://marketplace.visualstudio.com/items?itemName=twxs.cmake>`_, which
provides language coloring and autocompletion support.
I'm New to CMake. Help?
***********************
CMake Tools is not the same as CMake. There are many great resources around to
learn how to use CMake. A good video introduction can be found in Jason Turner's
`C++ Weekly - Intro to CMake <https://www.youtube.com/watch?v=HPMvU64RUTY>`_.
`CMake's documentation <https://cmake.org/cmake/help/latest/>`_ is also
available.
How Does it Work with C and C++ IntelliSense?
*********************************************
Orthogonally. Check the :ref:`How-do-I about IntelliSense <hdi.intellisense>`.
How Do I ``<XYZ>``?
*******************
Refer to the :ref:`how-do-i` page.
Will CMake Tools Ever Support ``<XYZ>``?
****************************************
Only if you voice support for it as a `GitHub issue
<https://github.com/vector-of-bool/vscode-cmake-tools/issues>`_. Open a feature
request or search for and provide feedback for an existing one!

175
docs/getting_started.rst
Просмотреть файл

@ -1,175 +0,0 @@
.. _getting-started:
Getting Started
###############
Assuming you already have a CMake project to configure, skip to the
:ref:`gs.configuring` section.
.. _gs.quickstart:
CMake Tools' *Quick Start*
**************************
CMake Tools provides a *CMake: Quick Start* command to quickly generate a very
bare-bones CMake project that can be configured and built with minimal friction.
Start by selecting *CMake: Quick Start* from the command palette:
.. image:: res/quickstart.png
:align: center
CMake Tools will then prompt you for the following information:
#. *The project name* - Will be written to the generated ``CMakeLists.txt`` and
a few initial source files.
#. *The project type* - Decides what initial source files to write. Not hugely
important as the project can be tweaked arbitrarily after generation.
Currently offers two choices:
- *Library* - Writes an ``add_library()`` command and a basic source and
header file.
- *Executable* - Writes an ``add_executable()`` command and a basic source
file with a *Hello, world* style ``main()`` function.
Once this information is collected, CMake will try an initial configure and
build of the project straight away.
.. _gs.configuring:
Configuring Your Project
************************
Configuring a project is simple, but has two steps before configuration can take
place.
Pre-Configure Steps
===================
Selecting a Kit
---------------
Before we can configure, you must select a *Kit*.
:ref:`(Read more about kits) <kits>`.
What are kits?
Kits represent a *toolchain*: A set of compilers, linkers, or other tools
that will be used to build a project. If you have no Kit selected, CMake
Tools will start by asking you to select a Kit.
When first opening a project, a status bar item will read **No Kit Selected**:
.. image:: res/no_kits.png
:align: center
To select a kit, click this statusbar button, or run the *Select a Kit* command
from the command palette. A quick-pick will appear:
.. image:: res/kit_selector.png
:align: center
Upon choosing a kit, the statusbar button will display the name of the active
kit:
.. image:: res/kit_selected.png
:align: center
The chosen kit will be remembered between sessions. Should the availability of
the kit change, the statusbar item may revert and you will be required to select
a kit again.
.. note::
If you try to configure your project without an active Kit selected, you
will be prompted to choose one before configuring can proceed.
CMake Tools will use the compilers/toolchain from the kit when building your
project.
Find out more on the :ref:`kits` page.
Selecting a Variant
-------------------
Similar to selecting a kit, we must select a *Variant*.
:ref:`(Read more about variants) <variants>`.
Before selecting a variant, the variant slot on the statusbar will read *Unknown*:
.. image:: res/no_variant.png
:align: center
To select a variant, click this statusbar button, or run the *Set build type*
command from the command palette. A quick-pick will appear:
.. image:: res/variant_selector.png
:align: center
The active build variant will be displayed on the same statusbar button, along
with the project name and extension status.
.. note::
Just like with kits, CMake Tools will ask you which variant to build if you
haven't already made a selection.
Variants can be customized to a wide variety of purposes. Find out more on the
:ref:`variants` page.
Running Configuration
=====================
Configuration can be run by clicking the project button in the statusbar and
changing the build type, by running the *CMake: Configure* command from the
command palette, or by running a build when configuration has not yet taken
place.
When configuration runs, the *CMake/Build* output panel will reveal and show
the live output from CMake as configuration runs:
.. image:: res/configure_output.png
:align: center
At this point, CMake Tools has loaded information about your project and you are
free to roam about the cabin.
.. seealso::
- :ref:`configuring`
.. _gs.building:
Building Your Project
*********************
More important than just configuring, you probably want to *build* your project
as well.
Building is simple: Run the *CMake: Build* command from the command palette:
.. image:: res/build_command.png
:align: center
.. note:: The default keybinding for this command is ``F7``.
You can also press the *Build* button in the statusbar:
.. image:: res/build_button.png
:align: center
While the the build is running, the *Build* button will be replaced with a
build progress bar:
.. image:: res/build_progress.png
:align: center
The build can be stopped by clicking the *Stop* button.
.. seealso::
- :ref:`building`
Accessing Build Results
***********************
By default, CMake Tools writes build output to the ``build/`` subdirectory of
your source tree, so build results are visible from the file explorer within
Visual Studio Code. This can be changed by changing the
:ref:`cmake.buildDirectory <conf-cmake.buildDirectory>` setting.

37
docs/how-to.md Normal file
Просмотреть файл

@ -0,0 +1,37 @@
# How To
This page links to documentation for common tasks.
## Create a new project
* From the command palette in VS Code, run the **CMake: Quick Start** command in a directory that doesn't have a `CMakeLists.txt` file.
* See the [CMake Tools on Linux tutorial](https://code.visualstudio.com/docs/cpp/cmake-linux#_create-a-cmake-hello-world-project)
## Configure a project
* From the command palette in VS Code, run the **CMake: Configure** command.
* See the *Configure Hello World* section of the [CMake Tools on Linux tutorial](https://code.visualstudio.com/docs/cpp/cmake-linux#_configure-hello-world), or the more in-depth [CMake Tools configure step](configure.md#the-cmake-tools-configure-step) documentation.
## Build a project
* From the command palette in VS Code, run the **CMake: Build** command, press the keyboard shortcut **F7**, or select the **Build** button in the status bar.
* See the *Build hello world* section of the [CMake Tools on Linux tutorial](https://code.visualstudio.com/docs/cpp/cmake-linux#_build-hello-world), or the more in-depth [Build with CMake Tools](build.md) documentation.
## Debug a project
* From the command palette in VS Code, run the **CMake: Debug Target** command, press the keyboard shortcut **Ctrl+F5**, or press the **Debug** button in the status bar.
* See the [CMake:Target debugging and launching](debug-launch.md) page for more information.
## Pass command-line arguments to the debugger
See [Debug using a launch.json file](debug-launch.md#debug-using-a-launchjson-file).
## Set up include paths for C++ IntelliSense
CMake Tools currently supports Microsoft's ms-vscode.cpptools extension. If the ms-vscode.cpptools extension is installed and enabled, then configuring your project will provide this integration automatically.
ms-vscode.cpptools will show a prompt confirming that you wish to use CMake Tools to provide the configuration information for your project. Accept this prompt to activate the integration. Subsequently, CMake Tools will provide and automatically update cpptools configuration information for each source file in your project.
## Next steps
- Explore the [CMake Tools documentation](README.md)

63
docs/how_do_i.rst
Просмотреть файл

@ -1,63 +0,0 @@
.. _how-do-i:
How Do I...
###########
This page talks about and links to documentation concerning common tasks and
processes.
Create a New Project?
*********************
- Run the *CMake: Quick Start* command in a directory with no ``CMakeLists.txt``.
Check out :ref:`gs.quickstart`.
Configure a Project?
********************
- Run the *CMake: Configure* command.
Check out the :ref:`Getting Started - Configuring <gs.configuring>` section,
or the more in-depth :ref:`configuring` documentation.
Build a Project?
****************
- Run the *CMake: Build* command, press :kbd:`F7`, or press the *Build* button
in the status bar.
See the :ref:`Getting Started - Building <gs.building>` section, or the
in-depth :ref:`building` documentation.
Debug a Project?
****************
- Run the *CMake: Debug Target* command, press :kbd:`Ctrl+F5`, or press the
*Debug* button in the status bar.
There's a lot to this one. Check out the :ref:`debugging` page for more
information.
Pass Command Line Argument to the Debugger?
*******************************************
See the :ref:`debugging.launch-json` documentation.
.. _hdi.intellisense:
Set Up Include Paths for C++ IntelliSense?
******************************************
CMake Tools currently supports Microsoft's cpptools extension.
If the cpptools extension is installed and enabled, then configuring your
project will attempt this integration automatically.
The first time this integration is attempted, cpptools will show a prompt
confirming that you wish to use CMake Tools to provide the configuration
information for your project. Accepting this prompt is all you need to do to
activate the integration. From then on, CMake Tools will provide and
automatically update cpptools' configuration information for each source file
in your project.
Happy IntelliSense-ing!

Двоичные данные
docs/images/cmake_kits_json.png Normal file
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

После

Ширина:  |  Высота:  |  Размер: 67 KiB

0
docs/res/custom_variant_selector.png → docs/images/custom_variant_selector.png
Просмотреть файл

Режим "рядом" Свайп Оверлей

До

Ширина:  |  Высота:  |  Размер: 35 KiB

После

Ширина:  |  Высота:  |  Размер: 35 KiB

Двоичные данные
docs/images/default_target.png Normal file
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

После

Ширина:  |  Высота:  |  Размер: 5.6 KiB

0
docs/res/launch_target.png → docs/images/launch_target.png
Просмотреть файл

Режим "рядом" Свайп Оверлей

До

Ширина:  |  Высота:  |  Размер: 8.4 KiB

После

Ширина:  |  Высота:  |  Размер: 8.4 KiB

0
docs/res/many_variants.png → docs/images/many_variants_example.png
Просмотреть файл

Режим "рядом" Свайп Оверлей

До

Ширина:  |  Высота:  |  Размер: 128 KiB

После

Ширина:  |  Высота:  |  Размер: 128 KiB

0
docs/res/target_selector.png → docs/images/target_selector.png
Просмотреть файл

Режим "рядом" Свайп Оверлей

До

Ширина:  |  Высота:  |  Размер: 51 KiB

После

Ширина:  |  Высота:  |  Размер: 51 KiB

Двоичные данные
docs/images/variants_yaml.png Normal file
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

После

Ширина:  |  Высота:  |  Размер: 58 KiB

42
docs/index.rst
Просмотреть файл

@ -1,42 +0,0 @@
.. CMake Tools documentation master file, created by
sphinx-quickstart on Sat Sep 23 14:46:28 2017.
CMake Tools for Visual Studio Code
==================================
CMake Tools is an extension designed to make working with CMake-based projects
as easy as possible. If you are new, check the :ref:`getting-started` docs. Also
check the :ref:`how-do-i` docs and the :ref:`faq`.
Contents:
.. toctree::
:maxdepth: 2
getting_started
kits
variants
configuring
building
debugging
settings
common_issues
troubleshooting
faq
how_do_i
development
changelog
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

139
docs/kits.md Normal file
Просмотреть файл

@ -0,0 +1,139 @@
# CMake kits
A _kit_ defines project-agnostic and configuration-agnostic info about how to build code. A kit can include:
- A set of compilers: these are locked at specific versions so that you can switch your compiler version quickly and easily.
- A Visual Studio installation: building for Visual Studio involves more than just finding the necessary compiler executable. Visual C++ requires certain environment variables to be set to tell it how to find and link to the Visual C++ toolchain headers and libraries.
- A toolchain file: The low-level way to instruct CMake how to compile and link for a target. CMake Tools handles toolchain files using kits.
Kits are mostly CMake-generator-agnostic (a CMake generator writes the input files for the native build system). Visual Studio kits have a preferred generator that will be used as a fallback to ensure a matching MSBuild and .sln generator are used for the Visual C++ compiler.
> **Note:**
> * If you use the [Ninja](https://ninja-build.org/) build system, don't worry about Visual Studio CMake Generators. CMake Tools will prefer Ninja if it is present, unless configured otherwise.
> * If you change the active kit while a project is configured, the project configuration will be re-generated with the chosen kit.
> * Using a kit is recommended but optional. If you don't use a kit, CMake will perform its own automatic detection.
## How kits are found and defined
When the CMake Tools extension runs for the first time, it will [scan for kits](#scan-for-kits) to find available toolchains. It populates the initial list of kits by looking in directories where known compilers are typically installed, and uses `vswhere` to find Visual Studio installations.
### User-local kits
A user-local kit is a kit that is available to a particular user for all projects open with CMake Tools.
The user-local list of kits is stored in the `cmake-kits.json` file, which you can edit by invoking **Edit CMake Kits** from the command palette:
![Example cmake_kits_json file](images/cmake_kits_json.png)
You can manually edit this file to define new global kits, however the contents of this file will be automatically updated by CMake Tools during a [scan for kits](#scan-for-kits).
> **Tip:**
> Define a new kit with your desired settings rather than modify kits that the CMake Tools extension creates so that your changes aren't overwritten during the next [scan for kits](#scan-for-kits).
### Project kits
Default user-local kits are available for all projects that use CMake Tools. To define a project-local kit, create a `.vscode/cmake-kits.json` file in the project directory. You manage the contents of this file manually, but CMake Tools will automatically reload and refresh when it sees this file added, removed, or changed. When changing kits, you can select from both user-local and project-local kits.
An example of when a project-local kit is useful is when the project defines its own CMake toolchain file(s). A [toolchain kit](#specify-a-toolchain) can be defined that specifies this file to be loaded. You can commit the `.vscode/cmake-kits.json` to source control and share it with other developers for easier collaboration using the named toolchain.
### Scan for kits
Update [user-local kits](#user-local-kits) by running **Scan for Kits** from the VS Code command palette. The following process is used to find available kits:
**1. Search the current PATH for compilers**
- CMake tools uses the `PATH` environment variable to get a list of directories where compilers can be found.
- CMake Tools looks for `gcc` and `clang` binaries on the `PATH` and gets version information from each executable it finds. For `gcc`, if a corresponding `g++` executable resides in the same directory it is added to the kit as the corresponding C++ compiler. The same applies for a `clang++` binary in the directory of a `clang` executable.
> **Note:**
> CMake Tools only automatically detects `Clang` and `GCC`. If you'd like auto-detection for more tools, please [open a Github issue](https://github.com/microsoft/vscode-cmake-tools/issues) with information about the compiler binary names and how to parse its version information.
**2. Find Visual Studio installations**
- CMake tools includes `vswhere.exe`, which it uses to find Visual Studio instances installed on the system.
- For each of `x86`, `amd64`, `x86_amd64`, `x86_arm`, `x86_arm64`, `amd64_x86`, `amd64_arm`, and `amd64_arm64`, CMake Tools checks for installed Visual C++ environments. A kit is generated for each existing MSVC toolchain that is found.
**3. Save results to the user-local kits file**
- The [user-local kit](#user-local-kits) `cmake-kits.json` file is updated with the new kit information.
> **Warning:**
> The name of each kit is generated from the kit compiler and version information. Kits with the same name will be overwritten. To prevent custom kits from being overwritten, give them unique names. CMake Tools will not delete entries from `cmake-kits.json`. It only adds and updates existing ones.
## Kit options
CMake defines different options that can be specified for each kit in their definition in `cmake-kits.json`, and these options can be mixed-and-matched as needed. For example, a single kit may request a Visual Studio environment, while specifying `clang-cl` as a compiler.
See [Configure CMake](configure.md) for more information about how kits are applied during configuration.
### Specify a compiler
To specify a compiler, list the path to the compiler in the `cmake-kits.json` file.
The most common CMake languages are `C` and `CXX`, and CMake Tools has built-in support for finding these. However, any language can be specified:
```xml
{
"name": "My Compiler Kit",
"compilers": {
"C": "/usr/bin/gcc",
"CXX": "/usr/bin/g++",
"Fortran": "/usr/bin/gfortran"
}
}
```
### Specify a toolchain
CMake Tools doesn't automatically detect toolchains, but you can specify a CMake toolchain file in a kit, like this:
```xml
{
"name": "Emscripten",
"toolchainFile": "/path/to/emscripten/toolchain.cmake"
}
```
CMake Tools will pass this path for `CMAKE_TOOLCHAIN_FILE` during configuration.
### Visual Studio
CMake Tools automatically sets up the environment for working with Visual C++. It is best to let CMake Tools generate the kits first, then duplicate and modify them:
```xml
{
"name": "A Visual Studio",
"visualStudio": "Visual Studio Build Tools 2017",
"visualStudioArchitecture": "amd64"
}
```
Keys:
> `visualStudio` : the name of a Visual Studio installation obtained by `VSWhere`.\
> `visualStudioArchitecture`: the Visual Studio target architecture that would be passed to the `vcvarsall.bat` file when entering the VS dev environment.
> **Note:**
> To use Visual C++, both `visualStudio` and `visualStudioArchitecture` must be specified. Omitting either one won't work.
### General options
The following additional options may be specified:
`preferredGenerator`
> The CMake generator that should be used with this kit if not the default. CMake Tools will still search in `cmake.preferredGenerators` from `settings.json`, but will fall back to this option if no generator from the user settings is available
`cmakeSettings`
> A JSON object passed as a list of cache settings when running CMake configure. Don't use this for project-specific settings and options. Instead, use `settings.json` for that purpose.
> This setting is most useful when the toolchain file respects additional options that can be passed as cache variables.
`environmentVariables`
> A JSON object of key-value pairs specifying additional environment variables to be defined when using this kit.
## Next steps
- Explore the [CMake Tools documentation](README.md)

243
docs/kits.rst
Просмотреть файл

@ -1,243 +0,0 @@
.. _kits:
CMake Kits
##########
A *kit* encompasses project-agnostic and configuration-agnostic information
about how to build code. A kit can include:
- *A set of compilers for some set of languages* - These are locked at specific
versions such that you can switch your compiler version quickly and easily.
- *A Visual Studio installation* - Building for VS is more complicated than
simply finding the necessary compiler executable. Visual C++ requires certain
environment variables to be set to tell it how to find and link to the
Visual C++ toolchain headers and libraries.
- *A toolchain file* - This is the lowest-level way to instruct CMake how to
compile and link for a target. CMake Tools handles toolchain files using
kits.
Kits are mostly CMake-generator-agnostic, although Visual Studio kits will have
a "preferred" generator that will be used as a fallback to ensure a matching
MSBuild and .sln generator is used for the Visual C++ compiler.
.. note::
If you use `Ninja <https://ninja-build.org/>`_ there is no need to worry
about Visual Studio CMake Generators. CMake Tools will prefer Ninja if it is
present unless configured otherwise.
.. note::
If you change the active Kit while a project is configured, the project
configuration will be re-generated with the chosen kit.
.. note::
Using a kit is recommended but optional. Opting-out of using kits will
cause CMake to perform its own automatic detection.
How Are Kits Found and Defined?
===============================
Upon first startup, CMake Tools will :ref:`scan the system <kit-scan>` for
available toolchains. It looks in certain directories for the presence of
compilers or Visual Studio installations (using ``vswhere``) to populate the
initial list of Kits.
.. _user-local-kits:
User-Local Kits
***************
User-local kits are kits that are available to a particular user for all
projects open with CMake Tools.
The user-local list of kits is stored in a user-owned file, which you can edit
by invoking *Edit CMake Kits* from the command palette. It will open the
``cmake-kits.json`` file:
.. image:: res/kits_json.png
:align: center
This file can be manually modified to define new global kits, and the contents
of this file will also be automatically controlled by CMake Tools via the
:ref:`automated kit scanning <kit-scan>`.
.. warning::
Don't modify any of the kits that CMake Tools defines itself: It will
overwrite any modifications during :ref:`kit scanning <kit-scan>`. See
below for more information.
Project Kits
************
The default user-local kits are available for all projects using CMake Tools
for a user. In addition, one can define project-local kits by creating a
``.vscode/cmake-kits.json`` file in the project directory. The contents of this
file must be managed manually, but CMake Tools will automatically reload and
refresh when it sees this file added, removed, or changed. When changing kits,
both user-local and project-local kits will be available for selection.
An example usage of project-local kits is if the project defines its own
CMake toolchain file(s). A :ref:`toolchain kit <kits.types.toolchain>` can be defined
that specifies this file to be loaded. The ``.vscode/cmake-kits.json`` file can
be committed to source control and shared with other developers for easier
collaboration on the named toolchain.
.. _kit-scan:
Scanning Process
****************
:ref:`user-local-kits` can be updated by running *Scan for Kits* in the
command palette. The following process occurs to find available kits:
#. **Search the current PATH for compilers**
CMake tools will use the ``PATH`` environment variable for a list of
directories where compilers can be found.
CMake Tools looks for ``gcc`` and ``clang`` binaries and asks each
executable for version information.
For gcc, if a corresponding ``g++`` executable resides in the same
directory it is added to the kit as the corresponding C++ compiler. The
same applies for a ``clang++`` binary in the directory of a ``clang``
executable.
.. note::
At the moment, CMake Tools will automatically detect *Clang* and
*GCC* only. If you'd like auto-detection for more tools,
please open an issue on the GitHub page with information about the
compiler binary names and how to parse its version information.
#. **Ask VSWhere about Visual Studio installations**
CMake tools includes a bundled ``vswhere.exe`` which it uses to ask about
existing Visual Studio instances installed on the system.
For each of ``x86``, ``amd64``, ``x86_amd64``, ``x86_arm``, ``x86_arm64``,
``amd64_x86``, ``amd64_arm``, and ``amd64_arm64``, CMake Tools will check
// for installed Visual C++ environments.
// A kit is generated for each existing MSVC toolchain.
#. **Save results to the user-local kits file**
When finished, the :ref:`user-local <user-local-kits>` ``cmake-kits.json``
file will be updated with the new kit information.
.. warning::
The ``name`` of each kit is generated from the kit compiler
and version information, and kits with the same name will be
overwritten in the file.
To prevent custom kits from being overwritten, give them unique names.
CMake Tools will not delete entries from ``cmake-kits.json``, only add
and update existing ones.
.. _kits.types:
Kit Options
===========
CMake defines several different options that can be specified on each kit in
their definition in ``cmake-kits.json``, and these options can be
mixed-and-matched as needed. For example, A single kit may request a
Visual Studio environment while specifying ``clang-cl`` as a compiler.
.. seealso::
- :ref:`configuring.how` - Explains how kits are applied during configuration
.. _kits.types.compiler:
Compilers
*********
Specifying language compilers is as simple as listing the paths to compilers
for CMake languages.
The most common CMake languages are ``C`` and ``CXX``, and CMake Tools has
built-in support for finding these, but any language can be specified:
.. code:: json
{
"name": "My Compiler Kit",
"compilers": {
"C": "/usr/bin/gcc",
"CXX": "/usr/bin/g++",
"Fortran": "/usr/bin/gfortran"
}
}
.. _kits.types.toolchain:
Toolchain
*********
CMake Tools will not automatically detect them, but you can also specify a
CMake toolchain file in a kit:
.. code:: json
{
"name": "Emscripten",
"toolchainFile": "/path/to/emscripten/toolchain.cmake"
}
CMake Tools will pass this path for ``CMAKE_TOOLCHAIN_FILE`` during configure.
.. _kits.types.vs:
Visual Studio
*************
CMake Tools will automatically setup the environment for working with Visual C++
when you use a Visual Studio code. It is advised to let CMake Tools
generate the kits first, then duplicate them and modify them.
.. code:: json
{
"name": "A Visual Studio",
"visualStudio": "Visual Studio Build Tools 2017",
"visualStudioArchitecture": "amd64"
}
The ``visualStudio`` key corresponds to a name of a Visual Studio installation
obtained from VSWhere. The ``visualStudioArchitecture`` key corresponds to a
Visual Studio target architecture that would be passed to the ``vcvarsall.bat``
file when entering the VS dev environment.
.. note::
To use Visual C++, *both* of ``visualStudio`` and
``visualStudioArchitecture`` *must* be specified. Omitting one will not
work.
.. _kits.common:
Generic Options
***************
In addition to the above options, the following may be specified:
.. _kits.common.preferredGenerator:
``preferredGenerator``
The CMake generator that should be used with this kit if not the default.
CMake Tools will still search in ``cmake.preferredGenerators`` from
``settings.json``, but will fall back to this option if no generator
from the user settings is available
.. _kits.common.cmakeSettings:
``cmakeSettings``
A JSON object that will be passed as a list of cache settings when running
CMake configure. Don't use this for project-specific settings and options:
Prefer to use the ``settings.json`` for that purpose.
This setting is most useful when the toolchain file respects additional
options that can be passed as cache variables.
``environmentVariables``
A JSON object of key-value pairs specifying additional environment
variables to be defined when using this kit.

Двоичные данные
docs/res/build_button.png
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 7.0 KiB

Двоичные данные
docs/res/build_command.png
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 26 KiB

Двоичные данные
docs/res/build_progress.png
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 21 KiB

Двоичные данные
docs/res/configure_output.png
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 108 KiB

Двоичные данные
docs/res/default_target.png
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 6.3 KiB

Двоичные данные
docs/res/kit_selected.png
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 17 KiB

Двоичные данные
docs/res/kit_selector.png
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 46 KiB

Двоичные данные
docs/res/kits_json.png
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 76 KiB

Двоичные данные
docs/res/no_kits.png
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 18 KiB

Двоичные данные
docs/res/no_variant.png
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 4.3 KiB

Двоичные данные
docs/res/quickstart.png
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 19 KiB

Двоичные данные
docs/res/variant_selector.png
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 24 KiB

Двоичные данные
docs/res/variants_yaml.png
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 59 KiB

311
docs/settings.rst
Просмотреть файл

@ -1,311 +0,0 @@
.. _settings:
Configuring CMake Tools
#######################
CMake Tools supports a variety of settings that can be set at the user or
workspace level via VSCode's ``settings.json`` file. This page talks about
the available options and how they are used.
.. seealso::
- :ref:`getting-started`
Options marked with *Supports substitution* allow variable references to appear
in their strings. See the :ref:`var-subs` section
Available Settings
==================
.. _conf-cmake.buildArgs:
``cmake.buildArgs``
*******************
An array of additional arguments to pass to ``cmake --build``.
- Default: ``[]`` (Empty array, no additional arguments)
- *Supports substitution*
.. seealso::
- :ref:`building.how`
.. _conf-cmake.buildBeforeRun:
``cmake.buildBeforeRun``
************************
If ``true``, build the launch/debug target before letting it execute.
- Default: ``true``
.. _conf-cmake.buildDirectory:
``cmake.buildDirectory``
************************
Specify the build directory (The root directory where ``CMakeCache.txt`` will
be generated).
- Default: ``${workspaceFolder}/build``.
- *Supports substitution*
.. _conf-cmake.buildEnvironment:
``cmake.buildEnvironment``
***************************
An object containing ``key : value`` pairs of environment variables,
which will be passed *ONLY* onto the compiler.
- Default: ``null`` (Unspecified)
- *Supports substitution*
.. _conf-cmake.buildToolArgs:
``cmake.buildToolArgs``
***********************
An array of additional arguments to pass to *the underlying build tool*.
- Default: ``[]`` (Empty array, no additional arguments)
- *Supports substitution*
.. seealso::
- :ref:`building.how`
.. _conf-cmake.cacheInit:
``cmake.cacheInit``
*******************
Path or list of paths to cache-initialization files. Passed to CMake via the
``-C`` command-line argument.
- Default: ``[]`` (Empty array, no cache initializer files)
.. _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.configureArgs:
``cmake.configureArgs``
***********************
Arguments to CMake that will be passed during the configure process.
- 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``
******************************
An object containing ``key : value`` pairs of environment variables,
which will be passed onto CMake *ONLY* when configuring.
- Default: ``null`` (Unspecified)
- *Supports substitution*
.. _conf-cmake.configureSettings:
``cmake.configureSettings``
***************************
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.copyCompileCommands:
``cmake.copyCompileCommands``
*****************************
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: ``null`` (Do not copy the file)
- *Supports substitution*
.. _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.environment:
``cmake.environment``
*********************
An object containing ``key : value`` pairs of environment variables,
which will be passed onto CMake when configuring and to the compiler.
- Default: ``null`` (Unspecified)
- *Supports substitution*
.. _conf-cmake.generator:
``cmake.generator``
*******************
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.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.loggingLevel:
``cmake.loggingLevel``
**********************
An enumerated string setting to change the amount of output CMake Tools
produces in its output channel. Set to one of "trace", "debug", "info", "note",
"warning", "error", or "fatal", with "trace" being the most verbose.
- Default: ``info``
.. note::
Regardless of the logging level, CMake Tools writes *all* levels of logging
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.
.. _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
=====================
Some options support the replacement of special values in their string value
using ``${variable}`` syntax. The following built-in variables are expanded:
``${workspaceRoot}``
**DEPRECATED**. The full path to the workspace root directory
``${workspaceFolder}``
The full path to the workspace root directory
``${workspaceRootFolderName}``
The name of the leaf directory in the workspace directory path
``${buildType}``
The current CMake build type, eg. ``Debug``, ``Release``, ``MinSizeRel``
``${buildKit}``
The current CMake kit name, eg. ``GCC 7.3.0``
``${generator}``
The name of the CMake generator, eg. ``Ninja``
``${projectName}``
**DEPRECATED**. Expands to the constant string "``ProjectName``"
.. note::
This was deprecated as CMake does not consider there to be *one*
project name to use. The concept of a single project does not work in
CMake, and this made this feature problematic and buggy. Alternatives
include ``${workspaceRootFolderName}``.
``${userHome}``
The full path to the current user's home directory
Environment Variables
*********************
Additionally, environment variables may be substituted with ``${env:VARNAME}``
and ``${env.VARNAME}`` syntax, where the string for the ``VARNAME`` environment
variable will be replaced. If the named environment variable is undefined, an empty
string will be expanded instead.
.. _variant-sub:
Variant Substitution
********************
Variant options may also be substituted with the ``${variant:VARIANTNAME}`` syntax,
where the name of the currently active choice of the provided ``VARIANTNAME`` variant
option will be replaced. If the variant option is undefined, an empty string will be
expanded instead.
Command Substitution
********************
CMake Tools also supports expanding of VSCode commands, similar to
``launch.json``. Running a command ``${command:foo.bar}`` will execute the
``foo.bar`` VSCode command and replace the string value. Beware of long-running
commands! It is unspecified when and how many times CMake Tools will execute a
command for a given expansion.

45
docs/troubleshoot.md Normal file
Просмотреть файл

@ -0,0 +1,45 @@
# Troubleshoot CMake Tools
## Common Issues and Resolutions
### Error: CMake Tools is unable to provide IntelliSense configuration
If you see a message that CMake Tools can't provide IntelliSense configuration, or see that #include directives are not resolving in the editor (the #include directive has a green underline), this means that the relevant source file is not attached to a CMake target.
If the file that receives this message is outside of your project, it is safe to ignore it.
If you are receiving this message for files within your project, you probably need to add the source file to a target.
This issue is most common with header files in a project. Header files should be included in the source list of a target. Even though CMake will not try to compile or process these headers in any special way, CMake Tools uses this information to provide a better user experience.
### Green squiggles beneath #include directives
See above.
### Debugging ignores launch.json
If the **Debug** button and Debug target features are ignoring your `launch.json` file, refer to [Debug using a launch.json file](debug-launch.md#debug-using-a-launchjson-file).
> **Important:** The target debugging feature is restricted to launching target executables with a default configuration in the `ms-vscode.cpptools` debugging engine.
### Reset CMake Tools extension state
CMake Tools persists workspace settings for things like the active target and variant. If this state is corrupted or inconsistent, open the VS Code command pallette and reset it by running the **CMake: Reset CMake Tools extension state** command.
Resetting the state will automatically reload the current workspace.
### Increase the logging level
CMake Tools provides optional logging that isn't enabled by default. Use the [cmake.loggingLevel](cmake-settings.md) setting to increase the amount of output written to the _CMake/Build_ output channel.
### Check the log file
Regardless of the user-visible log level, CMake Tools writes all log entries, for all levels, to a user-local log file. Open the VS Code command pallette and run the *CMake: Open the CMake Tools log file* command to view this log file.
This file is user-local, not workspace-local. This file includes all log entries since the extension was installed and may be very large.
## Get help
Check the [CMake Tools issue tracker](https://github.com/vector-of-bool/vscode-cmake-tools/issues) and [What's New](https://github.com/microsoft/vscode-cmake-tools/blob/develop/CHANGELOG.md) to see if your issue is already known/solved before submitting a question or bug report. Feel free to open an issue if your problem hasn't been reported.
Please visit [the support chat](https://gitter.im/vscode-cmake-tools/support). This is a community chat. Microsoft does not monitor it.

76
docs/troubleshooting.rst
Просмотреть файл

@ -1,76 +0,0 @@
.. _troubleshooting:
Troubleshooting CMake Tools
###########################
CMake Tools, like any piece of software, may misbehave. There are several things
to do to check what is going wrong.
.. note::
Should any of the below actions be necessary for any reason **be aware that
you have encountered a bug**.
If CMake Tools hasn't given you a useful help or error message, or has
behaved in a counter-intuitive way without being otherwise documented, then
the behavior can *and should* be considered a bug.
Please visit
`the support chat <https://gitter.im/vscode-cmake-tools/support>`_, and/or
check for or open a relevant
`GitHub issue <https://github.com/vector-of-bool/vscode-cmake-tools/issues>`_.
Reset the Extension State
*************************
CMake Tools persists certain workspace settings in an internal *memento* that is
opaque to the user. This includes things like the active target and variant.
If this state were to somehow be corrupted or inconsistent, this state can be
reset via the *CMake: Reset CMake Tools extension state* command.
.. warning::
Resetting the state will automatically reload the current workspace!
Increasing the Log Level
************************
CMake Tools exposes a lot of optional logging that isn't enabled by default.
The :ref:`conf-cmake.loggingLevel` setting can be used to increase the amount of
output written to the *CMake/Build* output channel.
Checking the Log File
*********************
Regardless of the user-visible log level, CMake Tools writes all log entries for
all levels to a user-local log file. This file can be opened with the
*CMake: Open the CMake Tools log file* command.
.. note::
This file is user-local, *not* workspace-local. This file includes all log
entries since the extension was installed. It may be very large.
Check for a GitHub Issue
************************
It is possible that other users have encountered the same problem before.
`Check the GitHub issues list for others encountering the same problem that
you have <https://github.com/vector-of-bool/vscode-cmake-tools/issues>`_.
Ask Around the Support Chat
***************************
CMake Tools has `a Gitter chat room for end-user support <https://gitter.im/vscode-cmake-tools/support>`_.
.. note::
People in this chat are volunteers and may not be available at all times of
the day. Please be patient.
Open a GitHub Issue
*******************
Issue reports are very welcome! CMake Tools is developed and maintained entirely
by volunteer work, so there is no rigorous QA process. End-user issue reports
are all we have to go on!
**And remember:** If your question isn't answered in this documentation,
**that's a documentation bug**!

178
docs/variants.md Normal file
Просмотреть файл

@ -0,0 +1,178 @@
# CMake variants
CMake Tools introduces the concept of _CMake variants_, which are a way to group together and combine a common set of build options and give them a name.
The main way to create a variant is via a `cmake-variants.json` or `cmake-variants.yaml` file.
Variants are a different concept than toolchains or toolsets. Those are handled by [CMake kits](kits.md).
By default, if a variants file isn't present, CMake Tools loads four variants that correspond to default CMake build types: **Release**, **Debug**, **MinRelSize**, and **RelWithDebInfo**. These variants do the following:
|Option | Description |
|---------|---------|
|`Debug` | Disables optimizations and includes debug info.|
|`Release`| Includes optimizations but no debug info.|
|`MinRelSize`| Optimizes for size. No debug info.|
|`RelWithDebInfo` | Optimizes for speed but also includes debug info. |
Selecting one of these variants configures and builds using the corresponding build type.
> **Important:**
> CMake Tools does not respect `CMAKE_CONFIGURATION_TYPES`. Only the default configuration types listed above are present. A custom variant file is required to load other build types.
For smaller projects, you don't need to provide a custom `cmake-variants.yaml` file. The default CMake build types work fine.
Large projects with more complex configuration options can specify additional build variants.
The variants file can be placed either in the root of the project directory, or in the project's `.vscode` subdirectory.
> **Note:**
> CMake Tools provides a YAML validation schema, but it is only checked in the editor when using the **YAML Support by Red Hat** extension.
You can use either `cmake-variants.json` or `cmake-variants.yaml` with the same result. The examples here use the YAML format, but can also be defined in JSON.
## Example YAML variants file
A simple two-setting `cmake-variants.yaml` might look like this:
![Example cmake-variants.yaml file](images/variants_yaml.png)
This file defines two variant settings: `buildType` and `useOpenGL`. Each has two options defined by `choices`. A combination of options, from a set of settings, forms a variant.
In total, the number of possible variants is defined by the cartesian product of possible choices. For example, two settings, each with two options, creates four variants. When you change the build type, CMake Tools will present the possible combinations in a quick pick list:
![Example variant quick pick list](images/custom_variant_selector.png)
When a `cmake-variants.json` or `cmake-variants.yaml` file is present, the options they define replace the default set of variants. This allows a project owner to define their own set of common build configurations, which can be distributed to others.
## Variant schema
The root of the variants must be an object, where each key represents a variant option. In the example above, a `buildType` option is defined for the kind of `CMAKE_BUILD_TYPE` we want. It also exposes `useOpenGL` which controls the `ENABLE_OPENGL` CMake option.
### Variant settings
Each setting in the variant is an object that may have the following keys:
|Key | Description |
|---------|---------|
|`default` | A string to set as the default choice for the variant option. The string here must correspond to an option from `choices`. |
|`description`| An optional string that describes what the option controls. CMake Tools ignores this string.|
|`choices` | A mapping of possible options for the setting. A variant setting can have an arbitrary number of options. The next section describes options. |
### Variant options
Variant options appear under the `choices`key for a variant setting. Each is required to have an unique name, but the name itself is unimportant to CMake Tools.
A choice may specify any of the following options, but must include the `short` option:
|Option |Description |
|---------|---------|
|`short`| A short human-readable string describing the option. |
|`long (Optional)` | A lengthier human-readable string describing the option. |
|`buildType (Optional)` | An optional string to set for `CMAKE_BUILD_TYPE` when the option is active. |
|`linkage (Optional)` | Either `static` or `shared`. Sets the value of `CMAKE_BUILD_SHARED_LIBS`. |
|`settings (Optional)` | A map of arbitrary CMake cache options to pass via the CMake command line with `-D`. Similar to the `cmake.configureSettings` in `settings.json`. |
|`env (Optional)` | A map of key-value string pairs specifying additional environment variables to set during CMake _configure_ (not build). These environment variables take precedence over environment variables from `settings.json`, the current [CMake kit](kits.md), and environment variables set by the system. |
The options above are only valid under entries in the `choices` map.
## How variants are applied
A variant is a specific combination of one option from each setting. When CMake Tools executes the configure step, it uses the values from the currently active variant to determine the values to pass to the CMake process, as follows:
1. Properties from all active options are merged. For `env` and `settings`, the objects themselves are merged. The merge order isn't specified, so conflicting properties in options will result in unspecified behavior.
1. All `settings` from the chosen options are passed as `-D` arguments to the CMake process.
1. The `buildType` is used for `CMAKE_BUILD_TYPE`, the `--config` flag for the build (for multi-configuration generators), and for the CTest `--config` flag.
1. If `linkage` is `true`, `BUILD_SHARED_LIBS` is set to `ON`. If `linkage` is `false`, `BUILD_SHARED_LIBS` is set to `OFF`. If not specified, `BUILD_SHARED_LIBS` isn't set on the CMake command line.
1. The environment variables from `env` are set for the CMake process.
## Large variant file example
Given the following variants file:
```yaml
buildType:
default: debug
choices:
debug:
short: Debug
long: Emit debug information
buildType: Debug
release:
short: Release
long: Optimize generated code
buildType: Release
asan:
short: Asan
long: Instrument with Address Sanitizer
buildType: Asan
tsan:
short: Tsan
long: Instrument with Thread Sanitizer
buildType: Tsan
linkage:
default: static
choices:
static:
short: Static
long: Create static libraries
linkage: static
shared:
short: Shared
long: Create shared libraries/DLLs
linkage: shared
engine:
default: ogl
choices:
ogl:
short: OpenGL
long: OpenGL rendering
settings:
ENGINE: OpenGL
d3d:
short: Direct3D
long: Direct3D rendering
settings:
ENGINE: Direct3D
vulkan:
short: Vulkan
long: Vulkan rendering
setting:
ENGINE: Vulkan
software:
short: Software
long: Software rendering
setting:
ENGINE: Software
network:
default: boost
choices:
boost:
short: Boost.Asio
long: Use Boost.Asio for networking
setting:
NETWORK: Boost
asio:
short: Asio
long: Use standalone-Asio for networking
setting:
NETWORK: Asio
net-ts:
short: NetTS
long: Use the C++ Networking TS for networking
setting:
NETWORK: net-ts
```
CMake Tools will present the cartesian product of all options. For the example above, it will produce 4 × 2 × 4 × 3 = 96 different variants:
![Example of many variants](images/many_variants_example.png)
This example creates many possible variants, but may not be unreasonable if you are building complex software. CMake Tools shows all of the possible combinations, and persists your selection between sessions.

244
docs/variants.rst
Просмотреть файл

@ -1,244 +0,0 @@
.. _variants:
CMake Variants
##############
CMake Tools introduces the concept of *CMake Variants*, a way to group together
and combine a common set of build options and give them a useful name. The main
interface for creating and building variants is ``cmake-variants.json``, or
``cmake-variants.yaml``.
The idea of "variants" are separate from the concept of toolchains/toolsets,
which are handled via :ref:`Kits <kits>`.
By default, if no variants file is present, CMake Tools will load four variants,
each corresponding to a default CMake build type: *Release*, *Debug*,
*MinSizeRel*, and *RelWithDebInfo*. Selecting one of these variants will
configure and build with that build type.
.. note::
CMake Tools does not presently respect ``CMAKE_CONFIGURATION_TYPES``. Only
the default four will be present. A custom variant file is required to load
these build types.
For smaller or simple projects, providing a custom ``cmake-variants.yaml`` is
unnecessary, and the default CMake build types will work just fine. Large
projects with more complex configuration options may want to specify
additional build variants.
The variants file can be placed in the root of the project directory, or in the
``.vscode`` subdirectory for the project.
.. note::
CMake Tools provides a YAML validation schema, which is only checked in the
editor when using the *YAML Support by Red Hat* extension.
You can use either ``cmake-variants.json`` or ``cmake-variants.yaml``. Both
will have the same end result.
The examples in this page will use the YAML format, but everything can be
done in the JSON format as well.
What does it look like?
=======================
A simple two-setting ``cmake-variants.yaml`` might look like this:
.. image:: res/variants_yaml.png
:align: center
This file defines two variant **settings**: *buildType* and *useOpenGL*. They
each have two **options** defined by the ``choices`` key. A combination of the
**options** from a set of **settings** forms a **variant**.
In total, the number of possible **variants** is defined by the cartesian
product of the possible choices. Two **settings** each with two **options**
creates *four* variants. When we ask to change the build type, CMake Tools will
present each possible combination in a quickpick:
.. image:: res/custom_variant_selector.png
:align: center
When a ``cmake-variants.json`` or ``cmake-variants.yaml`` file is present, the
options defined therein will replace the default set of variants CMake Tools
would otherwise present. This allows a project owner to define their own set of
common build configurations that can be distributed downstream.
The Variant Schema
==================
The root of the variants must be an object, where each key represents a
tweakable variant option. In the example above, we expose a ``buildType`` option
for what kind of ``CMAKE_BUILD_TYPE`` we want. We also expose a ``useOpenGL``
that controls the ``ENABLE_OPENGL`` CMake option.
Variant Settings
****************
Each *setting* in the variant is an object with only the following keys:
``default``
A string to set as the default *choice* for the variant option. The string
here must correspond to an option from ``choices``.
``description``
An optional string to describe what the option controls. CMake Tools ignores
this string.
``choices``
A mapping of possible options for the setting. A variant setting can have an
arbitrary number of possible options. See the section below on options.
.. _variants.opts:
Variant Options
***************
Variant options appear under the ``choices`` key for a variant setting. Each is
required to have an unique name, but the name itself is unimportant to CMake
Tools.
A choice may specify any of the following options (the only requirement is the
``short``):
``short``
A short human-readable string to describe the option.
``long`` (Optional)
A lengthier human-readable string to describe the option.
``buildType`` (Optional)
An optional string to set for ``CMAKE_BUILD_TYPE`` when the option is
active.
``linkage`` (Optional)
Either ``static`` or ``shared``. Sets the value of
``CMAKE_BUILD_SHARED_LIBS``. This value is optional.
``settings`` (Optional)
A map of arbitrary CMake cache options to pass via the CMake command line
with ``-D``. Similar to the ``cmake.configureSettings`` in
``settings.json``.
``env`` (Optional)
A map of key-value string pairs specifying additional environment variables
to set during CMake *configure* (not build). These environment variables
take precedence over environment variables from ``settings.json``, the
currently set :ref:`kit <kits>`, and environment variables set by the
system.
The above options are only valid under entries in the ``choices`` map.
How Variants Are Applied
========================
A variant is a specific combination of one *option* from each of the defined
*settings*. When CMake Tools executes the configure step, it will use the
values from the currently active variant to determine the values to pass to the
CMake process:
#. Properties from all active options are merged. For ``env`` and ``settings``,
the objects themselves are merged. The merge order is unspecified, so
conflicting properties in options will result in unspecified behavior.
#. All ``settings`` from the chosen options are passed as ``-D`` arguments to
the CMake process.
#. The ``buildType`` is used for ``CMAKE_BUILD_TYPE``, the ``--config``
flag for the build (For multi-conf generators), and for the CTest
``--config`` flag.
#. If ``linkage`` is ``true``, ``BUILD_SHARED_LIBS`` is set to ``ON``. If
``linkage`` is ``false``, ``BUILD_SHARED_LIBS`` is set to ``OFF``. If not
specified, ``BUILD_SHARED_LIBS`` will not be set on the CMake command line.
#. The environment variables from ``env`` are set for the CMake process.
A Big Example
=============
Suppose the following variants file:
.. code-block:: yaml
buildType:
default: debug
choices:
debug:
short: Debug
long: Emit debug information
buildType: Debug
release:
short: Release
long: Optimize generated code
buildType: Release
asan:
short: Asan
long: Instrument with Address Sanitizer
buildType: Asan
tsan:
short: Tsan
long: Instrument with Thread Sanitizer
buildType: Tsan
linkage:
default: static
choices:
static:
short: Static
long: Create static libraries
linkage: static
shared:
short: Shared
long: Create shared libraries/DLLs
linkage: shared
engine:
default: ogl
choices:
ogl:
short: OpenGL
long: OpenGL rendering
settings:
ENGINE: OpenGL
d3d:
short: Direct3D
long: Direct3D rendering
settings:
ENGINE: Direct3D
vulkan:
short: Vulkan
long: Vulkan rendering
setting:
ENGINE: Vulkan
software:
short: Software
long: Software rendering
setting:
ENGINE: Software
network:
default: boost
choices:
boost:
short: Boost.Asio
long: Use Boost.Asio for networking
setting:
NETWORK: Boost
asio:
short: Asio
long: Use standalone-Asio for networking
setting:
NETWORK: Asio
net-ts:
short: NetTS
long: Use the C++ Networking TS for networking
setting:
NETWORK: net-ts
CMake Tools will present the cartesian product of all options, meaning the
above will produce 4 × 2 × 4 × 3 = *ninety-six* different variants:
.. image:: res/many_variants.png
:align: center
Of course this is quite a lot of possible variants, but such is the way with
some complex software. CMake Tools will readily any helpfully show all
combinations, and persist the selection between sessions.