Consolidate CMake Tools documentation #1324

TylerMSFT · 2020-06-20T00:26:02Z

This consolidates all of the CMake Tools documentation.

The purpose of this change

Bring all of the documentation on the previous site, to the Microsoft CMake Tools github.

…ools into twhitney-cmakeLibrary

bobbrow

Still reviewing... Submitting a few comments for the files I got through this morning.

bobbrow · 2020-06-23T17:36:39Z

docs/changelog.md

@@ -0,0 +1,127 @@
+# Changelog and History


My impression is that we don't need to keep this legacy changelog around. I'd be fine if you deleted it.

Done. I assume I should continue to point to What's new (from the faq) at https://github.com/microsoft/vscode-cmake-tools/blob/develop/CHANGELOG.md (this is the current changelog, I think)

bobbrow · 2020-06-23T17:42:34Z

docs/cmake-settings.md

+
+### Command substitution
+
+CMake Tools can expand VS Code commands. for example, you can expand the `launch.json` command using the syntax `${command:launch.json}`


launch.json is not a command. A better example would be ${command:cmake.launchTargetPath}

bobbrow · 2020-06-23T17:47:13Z

docs/configure.md

+
+## How CMake Tools configures
+
+CMake Tools drives CMake via CMake Server, an execution mode of CMake that provides a persistent connection to get project information.


We use CMake Server for older versions of Cmake (3.7 - 3.14, I believe). If using version 3.14.6 or newer, we use cmake-file-api which provides the project information via a file that is persisted to disk.

Since we document what we currently have, rather than the history of where we've been, I changed this to say that it uses the cmake-file-api and dropped mention of cmake server.

There was another reference to the cmake server in this topic, which I also changed. It talked about setting environment variables for the cmake server process. I changed it like so: "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."

esweet431

Thanks for your work here, I left a few comments.

esweet431 · 2020-06-25T15:51:18Z

docs/cmake-settings.md

@@ -0,0 +1,66 @@
+# Configure CMake tools


It's always confusing to me that we use the word 'configure' as a specific step in the CMake build process AND as a general verb. I run into this, too. Any way we can use a different word here? Glancing through the TOC it's potentially confusing that there is a section called "Configure" and a section called "Configure CMake Tools". Maybe the latter can be "CMake Tools Settings"?

This was confusing me too. I left it because I assumed it was terminology that the cmake community was familiar with. I like your idea for CMake tools settings and will ripple that change through the various articles.

I've updated the configure.md and cmake-settings.md files to try to separate these ideas. I have the concept of configuring CMake tools, which I've renamed CMake tool settings, and then in configure.md I tried to be more clear about the 'CMake configure process' and changed headings accordingly.

esweet431 · 2020-06-25T15:52:14Z

docs/cmake-settings.md

@@ -0,0 +1,66 @@
+# Configure 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 topic  covers the available options and how they are used.


Maybe add a link to learn about user vs workspace settings?
https://code.visualstudio.com/docs/getstarted/settings

Good idea. Done.

esweet431 · 2020-06-25T16:01:32Z

docs/cmake-settings.md

+
+## CMake settings
+
+|Setting  |Description | Default value | Supports substitution |


There are two commands we've added since taking over the extension that aren't captured here:
cmake.autoSelectActiveFolder | If 'false', your active folder will only change if you manually run the CMake: Select Active Folder command | 'true' | no
cmake.cmakeCommunicationMode | Specifies the protocol used to communicate between the extension and CMake | 'automatic' | no

esweet431 · 2020-06-25T16:09:59Z

docs/debug-launch.md

+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 only supported when CMake is in  _CMake Server_ mode. This mode is enabled automatically for CMake versions 3.7.2 and above. It is not available on older versions.


This should be "...when CMake is using CMake server mode or file-based API. These modes are enabled automatically...." (or something to show that debugging is supported by both CMake server mode and file-based API)

I've changed this to read: 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.

esweet431 · 2020-06-25T16:17:21Z

docs/kits.md

+You can manually edit this file to define new global kits. The contents of this file will be automatically updated by CMake Tools during a [scan for kits](#scan-for-kits).
+
+> **Warning:**
+> Don't modify kits that the CMake Tools extension creates because your changes will be overwritten during the next [scan for kits](#scan-for-kits).


Maybe add something - "You should instead define a new kit with you desired modifications" to be explicit about the preferred behavior

I modified this section to read:

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.

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.

…ools into twhitney-cmakeLibrary

bobbrow

Thank you so much @TylerMSFT!

Tyler Whitney added 11 commits June 12, 2020 17:47

files to port

ad28a73

Merge branch 'develop' of https://github.com/microsoft/vscode-cmake-t…

1518a1b

…ools into twhitney-cmakeLibrary

draft

c821be1

Merge branch 'develop' of https://github.com/microsoft/vscode-cmake-t…

af5a34c

…ools into twhitney-cmakeLibrary

Merge branch 'develop' of https://github.com/microsoft/vscode-cmake-t…

1260928

…ools into twhitney-cmakeLibrary

draft

fcf8c63

last draft pass

fe79a82

move ported docs into docs and remove sphinx related

98c6947

cleanup

8a64eb0

fix links

cd0e450

clean up links and :kbd:

2be5cf4

bobbrow reviewed Jun 23, 2020

View reviewed changes

esweet431 reviewed Jun 25, 2020

View reviewed changes

Merge branch 'develop' of https://github.com/microsoft/vscode-cmake-t…

f2fd21c

…ools into twhitney-cmakeLibrary

bobbrow mentioned this pull request Jun 25, 2020

Remove duplicate "a" #1333

Closed

Tyler Whitney added 3 commits June 25, 2020 11:16

tech review feedback

0f66f43

fix links

9fdfebc

remove stray '.'

1c0d146

bobbrow approved these changes Jun 26, 2020

View reviewed changes

bobbrow merged commit 28712f5 into microsoft:develop Jun 26, 2020

github-actions bot locked and limited conversation to collaborators Jan 31, 2022


		### Command substitution

		CMake Tools can expand VS Code commands. for example, you can expand the `launch.json` command using the syntax `${command:launch.json}`


		## How CMake Tools configures

		CMake Tools drives CMake via CMake Server, an execution mode of CMake that provides a persistent connection to get project information.

		@@ -0,0 +1,66 @@
		# Configure 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 topic covers the available options and how they are used.


		## CMake settings

		\|Setting \|Description \| Default value \| Supports substitution \|

Consolidate CMake Tools documentation #1324

Consolidate CMake Tools documentation #1324

Uh oh!

Conversation

TylerMSFT commented Jun 20, 2020

This consolidates all of the CMake Tools documentation.

The purpose of this change

Uh oh!

bobbrow left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

esweet431 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bobbrow left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!