Share via

Questions about custom build steps

Martin Galvan 0 Reputation points
2024-05-21T07:03:17.48+00:00

Hi, this is the same question posted at https://github.com/MicrosoftDocs/cpp-docs/pull/5034

I'm looking at the pages for adding custom build steps to an existing .vcxproj file (namely https://learn.microsoft.com/en-us/cpp/build/how-to-add-a-custom-build-step-to-msbuild-projects?view=msvc-170 and https://learn.microsoft.com/en-us/cpp/build/how-to-add-custom-build-tools-to-msbuild-projects?view=msvc-170) but can't find a clear explanation on the semantics of the XML elements involved. For example, the second page I linked shows the following:

<ItemGroup>
  <CustomBuild Include="faq.txt">
    <Message>Copying readme...</Message>
    <Command>copy %(Identity) $(OutDir)%(Identity)</Command>
    <Outputs>$(OutDir)%(Identity)</Outputs>
  </CustomBuild>
</ItemGroup>

What are the possible attributes of CustomBuild? What does Include do? What is %(Identity)? And so on.

I've actually cloned the cpp-docs repository and couldn't find any references to Identity other than https://learn.microsoft.com/en-us/troubleshoot/developer/visualstudio/cpp/language-compilers/add-references-managed so I believe the documentation is lacking here.

Visual Studio
Visual Studio
A family of Microsoft suites of integrated development tools for building applications for Windows, the web and mobile devices.
4,726 questions

1 answer

Sort by: Most helpful
Most helpful Newest Oldest
  1. Tianyu Sun-MSFT 28,066 Reputation points Microsoft Vendor
    2024-05-21T08:51:22.3133333+00:00

    Hello @Martin Galvan,

    Welcome to Microsoft Q&A forum.

    The attributes that you want to know are about MSBuild. Some are Item(MSBuild) elements.

    The explanation might not be collected in one document but scattered across different documents.

    Include is a normal attribute, you may find the explanation here: Attributes – Include

    Optional attribute.

    The file or wildcard to include in the list of items.

    As you can see, a file called faq.txt is included.

    %(Identity), there are two things. One is % or %(), the other is (Identity), or Identity.

    % is a special character in MSBuild, it usually means "referencing metadata". You may find the description here: Special characters - %

    Identity is normally used together with %(), you may find the description here: MSBuild well-known item metadata - %(Identity)

    The item specified in the Include attribute. For example: faq.txt.

    Besides, $ character means "referencing properties", $(OutDir) means path to the output file directory.

    CustomBuild should be a task(MSBuild task). As you can see => CustomBuild task, it is used to build C++ projects.

    I agree with you that the documentation that you are referring to, can be improved to add some necessary explanations/descriptions for these attributes, maybe links or short descriptions.

    I will help you to report the feedback about the documentation.

    Sincerely,

    Tianyu

    If the answer is the right solution, please click "Accept Answer" and kindly upvote it. If you have extra questions about this answer, please click "Comment".

    Note: Please follow the steps in our documentation to enable e-mail notifications if you want to receive the related email notification for this thread.

    0 comments