cmake: surface headers in Visual Studio solution #1222

cnaples79 · 2025-10-06T12:38:45Z

Summary

add the public GSL headers to the interface target so Visual Studio solutions list them automatically
group the headers under a "Header Files" node and surface key repo documents as Solution Items when generating a VS solution

Rationale

Developers opening the generated Visual Studio solution couldn't discover headers or project metadata without manual include navigation. Adding the files directly to the solution keeps intellisense and browsing consistent with typical VS layout (matching the reporter's expectation).

Changes

enumerate GSL headers and append them to 'target_sources'
define Visual Studio source groups and VS_SOLUTION_ITEMS for docs/licenses when using a VS generator
no functional code changes; header-only interface remains unchanged

Fixes #1216

davidhunter22 · 2025-10-07T19:47:33Z

Hi I tried cloning you repository and doing an out of tree build using CMake 4.1.2

cmake ../src

where the src directory is a clone of cnaples79:fix-1216-vs-solution-items with no changes.
I get errors like

  Target "GSL" INTERFACE_SOURCES property contains path:

    "C:/Users/.../src/include/gsl/algorithm"

  which is prefixed in the source directory.

I read a few things on the message and they were talking about adding header using INTERFACE or PUBLIC like

target_sources(GSL INTERFACE
    ${GSL_HEADER_FILES}
    $<BUILD_INTERFACE:${GSL_SOURCE_DIR}/GSL.natvis>
)

I tried changing the INTERFACE to PRIVATE and the CMake ran fine.
I assume I am doing something dumb, I am in now way a CMake expert!

cnaples79 · 2025-10-07T22:08:13Z

@davidhunter22 Hey! Yeah it is due to the later versions of CMake past 4.1.x. Try again and let me know if you still get any errors.

Copilot

Pull Request Overview

This PR enhances Visual Studio integration by making GSL headers and project metadata visible in generated Visual Studio solutions. The changes improve developer experience by providing proper file organization and discoverability within the IDE.

Explicitly lists all GSL headers in the CMake target to surface them in Visual Studio
Organizes headers under a "Header Files" group in the solution explorer
Adds key project documents as solution items for easy access

CMakeLists.txt

davidhunter22 · 2025-10-08T02:09:25Z

Looking at the changes I was wondering if there was a simpler way.
I noticed that there is a CMakeLists.txt in the include directory.
I tried moving all the stuff to do with the GSL target into this CMakeLists.txt
This seemed to make most things work without doing all the path manipulation, including the install step.
Note I only tested on VS so far.

I also wondered if the header files could be added to the GSL project as a FILE_SET. This also seemed to work well.

carsonRadtke

Thanks for the PR! The pipeline looks good, but can you address these couple comments?

CMakeLists.txt

carsonRadtke · 2025-10-08T03:39:40Z

CMakeLists.txt

+    foreach(header ${GSL_HEADER_FILES})
+        list(APPEND GSL_HEADER_ABSOLUTE_PATHS ${GSL_SOURCE_DIR}/include/${header})
+    endforeach()
+    source_group(TREE ${GSL_SOURCE_DIR}/include PREFIX "Header Files" FILES ${GSL_HEADER_ABSOLUTE_PATHS})


issue: Based on your PR description, it sounds like this should appear in the solution adjacent to "Solution Items"? I'm not seeing anything.

> cmake --version > PS D:\GSL\build> cmake --version cmake version 4.1.0

I added a source_group call, the docs should land in the solution items node now.

carsonRadtke

Unfortunately, this approach requires features from CMake 4.0.0. Right now, we can't force that on our customers, so we will need a different approach. I have outlined my suggestion in one of the comments but would also like to hear of any alternatives that exist.

carsonRadtke · 2025-10-08T04:13:41Z

CMakeLists.txt

+    RELATIVE "${CMAKE_CURRENT_SOURCE_DIR}/include"
+    "${CMAKE_CURRENT_SOURCE_DIR}/include/gsl/*"
+)
+list(SORT GSL_HEADER_FILES)


nit: According to the docs, the result of file(GLOB, ... is already sorted.

https://cmake.org/cmake/help/latest/command/file.html#filesystem

carsonRadtke · 2025-10-08T04:30:14Z

CMakeLists.txt

+list(SORT GSL_HEADER_FILES)
+
+# Build/install interface lists ensure CMake is happy when exporting headers via
+# INTERFACE sources. Absolute paths would be rejected by newer CMake versions


nit: "Newer" may be true now but won't be true in the future. Any chance you know which version of CMake starts throwing the error?

I believe it's 4.1.2, below that didn't throw for me.

carsonRadtke · 2025-10-08T05:23:15Z

CMakeLists.txt

+        ${GSL_SOURCE_DIR}/ThirdPartyNotices.txt
+    )
+
+    set_property(DIRECTORY PROPERTY VS_SOLUTION_ITEMS ${GSL_SOLUTION_FILES})


issue: The VS_SOLUTION_ITEMS property is new in CMake 4.0.0. At this time, we want to maintain backwards compatibility with older CMakes. Apologies for not catching this the first time around, but we will need to figure out something else.

From what I understand, before 4.0.0 there was no way of adding arbitrary files to VS solutions. What you'll need to do is create a custom target and add the files in the GSL workspace to that target. Something like:

if (CMAKE_GENERATOR MATCHES "Visual Studio") file(GLOB GSL_WORKSPACE_FILES "${CMAKE_CURRENT_SOURCE_DIR}/include/gsl/*") list(APPEND GSL_WORKSPACE_FILES ${GSL_SOURCE_DIR}/.clang-format ${GSL_SOURCE_DIR}/.gitattributes ${GSL_SOURCE_DIR}/.gitignore ${GSL_SOURCE_DIR}/CMakeSettings.json ${GSL_SOURCE_DIR}/CONTRIBUTING.md ${GSL_SOURCE_DIR}/LICENSE ${GSL_SOURCE_DIR}/README.md ${GSL_SOURCE_DIR}/SECURITY.md ${GSL_SOURCE_DIR}/ThirdPartyNotices.txt ) target_sources(GSL PRIVATE ${GSL_WORKSPACE_FILES}) endif()

And that should probably be the bulk of the change.

https://cmake.org/cmake/help/latest/prop_dir/VS_SOLUTION_ITEMS.html

carsonRadtke · 2025-10-08T05:56:55Z

CMakeLists.txt

+endforeach()
+
+target_sources(GSL INTERFACE
+    ${GSL_HEADER_INTERFACE_SOURCES}


suggestion: According to https://github.com/microsoft/GSL/pull/1112/files#r1190452831 this only affects VS solutions. Let's move it into your new if (CMAKE_GENERATOR MATCHES "Visual Studio") block and combine it with the other target_sources (which doesn't yet exist; see my comment about VS_SOLUTION_ITEMS).

cnaples79 · 2025-10-08T10:41:36Z

@carsonRadtke No worries! I'll do some more research to see if there's a better solution or may end up going with your suggestion. I'll update the PR.

davidhunter22 · 2025-10-08T14:02:32Z

On using the VS_SOLUTION_ITEMS property. This is obviously a magic property name added in 4.0.
On older version it is not magic and I believe does nothing.
Given that this only makes files visible in generated VS solutions, files which have never been visible before and that this only applies to people actually building GSL itself I am wondering what backwards compatibility there is?
I would say this is a new feature that only works if you are using 4.0 of CMaje or above. If you are using earlier than that you are "compatible" in that the behaviour has not changed.

carsonRadtke · 2025-10-08T16:14:38Z

On using the VS_SOLUTION_ITEMS property. This is obviously a magic property name added in 4.0. On older version it is not magic and I believe does nothing. Given that this only makes files visible in generated VS solutions, files which have never been visible before and that this only applies to people actually building GSL itself I am wondering what backwards compatibility there is? I would say this is a new feature that only works if you are using 4.0 of CMaje or above. If you are using earlier than that you are "compatible" in that the behaviour has not changed.

@davidhunter22 -- I see where you're coming from, but this is effectively a feature implementation for GSL and it should work for all customers (in this case, the customers are y'all: the contributors) who meet the dependency requirements. If there was no possible way for this to work pre-4.0.0, I would be more open to a VS_SOLUTION_ITEMS solution, but since we can do it in a way that is compatible with 3.* and 4.*, I'd like to see that.

carsonRadtke · 2025-10-20T17:19:03Z

@cnaples79 -- Do you need any assistance with this? It is close, but I'm still waiting on a few comments to be resolved before merging!

cmake: surface headers in Visual Studio solution

45dcb68

cmake: fix interface header paths

5146d31

carsonRadtke self-assigned this Oct 8, 2025

carsonRadtke added Type: Enhancement Suggests an improvement or new feature Status: Review Needed Needs review from GSL maintainers labels Oct 8, 2025

carsonRadtke added this to Microsoft/GSL Pull Requests In-Flight Oct 8, 2025

carsonRadtke moved this to Ready for Review in Microsoft/GSL Pull Requests In-Flight Oct 8, 2025

carsonRadtke requested a review from Copilot October 8, 2025 00:01

Copilot AI reviewed Oct 8, 2025

View reviewed changes

CMakeLists.txt Outdated Show resolved Hide resolved

CMakeLists.txt Show resolved Hide resolved

carsonRadtke reviewed Oct 8, 2025

View reviewed changes

carsonRadtke moved this from Ready for Review to Changes Requested in Microsoft/GSL Pull Requests In-Flight Oct 8, 2025

carsonRadtke added Status: In Progress Currently being worked on and removed Status: Review Needed Needs review from GSL maintainers labels Oct 8, 2025

cmake: glob headers and surface solution docs

d43635b

carsonRadtke requested changes Oct 8, 2025

View reviewed changes

davidhunter22 mentioned this pull request Oct 8, 2025

Guard includes of standard library headers so users can use import std #1218

Open

cmake: avoid VS solution items property

8fce2e7

carsonRadtke assigned cnaples79 and unassigned carsonRadtke Oct 15, 2025

cmake: surface headers in Visual Studio solution #1222

Are you sure you want to change the base?

cmake: surface headers in Visual Studio solution #1222

Uh oh!

Conversation

cnaples79 commented Oct 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Rationale

Changes

Uh oh!

davidhunter22 commented Oct 7, 2025

Uh oh!

cnaples79 commented Oct 7, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

Uh oh!

davidhunter22 commented Oct 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

carsonRadtke left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

carsonRadtke Oct 8, 2025

Choose a reason for hiding this comment

Uh oh!

cnaples79 Oct 8, 2025

Choose a reason for hiding this comment

Uh oh!

carsonRadtke left a comment

Choose a reason for hiding this comment

Uh oh!

carsonRadtke Oct 8, 2025

Choose a reason for hiding this comment

Uh oh!

carsonRadtke Oct 8, 2025

Choose a reason for hiding this comment

Uh oh!

cnaples79 Oct 8, 2025

Choose a reason for hiding this comment

Uh oh!

carsonRadtke Oct 8, 2025

Choose a reason for hiding this comment

Uh oh!

carsonRadtke Oct 8, 2025

Choose a reason for hiding this comment

Uh oh!

cnaples79 commented Oct 8, 2025

Uh oh!

davidhunter22 commented Oct 8, 2025

Uh oh!

carsonRadtke commented Oct 8, 2025

Uh oh!

carsonRadtke commented Oct 20, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

cnaples79 commented Oct 6, 2025 •

edited

Loading

davidhunter22 commented Oct 8, 2025 •

edited

Loading