vcpkg em projetos do MSBuild

Métodos de integração

Integração em todo o perfil do usuário

Para usar vcpkg em seus projetos do MSBuild, execute o seguinte comando:

vcpkg integrate install

Você só precisa executar o comando vcpkg integrate install na primeira vez que quiser habilitar a integração do MSBuild. Isso permite a integração do MSBuild para todos os seus projetos existentes e futuros.

Se você tiver várias instâncias de vcpkg, poderá usar o vcpkg integrate install comando para atualizar qual instância vcpkg é usada no MSBuild. Use vcpkg integrate remove para remover a integração global do MSBuild.

Esse método de integração adiciona automaticamente pacotes instalados em vcpkg às seguintes propriedades do projeto: Incluir Diretórios, Diretórios de Link e Bibliotecas de Link. Além disso, isso cria uma ação pós-compilação que garante que todas as DLLs necessárias sejam copiadas para a pasta de saída da compilação. Isso funciona para todas as soluções e projetos usando Visual Studio 2017 ou mais recente.

Isso é tudo o que você precisa fazer para a grande maioria das bibliotecas. No entanto, algumas bibliotecas executam comportamentos conflitantes, como redefinir main(). Como você precisa escolher por projeto quais dessas opções conflitantes você deseja, você deve adicionar manualmente essas bibliotecas às entradas do vinculador.

Aqui estão alguns exemplos em que a vinculação manual é necessária (não uma lista completa):

• O Gtest fornece gtest, gmock, gtest_main e gmock_main
• O SDL2 fornece SDL2main
• O SFML fornece sfml-main
• Boost.Test fornece boost_test_exec_monitor

Para obter uma lista completa de todos os pacotes instalados, execute vcpkg owns manual-link.

Importar .props e .targets

o vcpkg também pode ser integrado a projetos do MSBuild por meio da importação explícita dos arquivos scripts/buildsystems/vcpkg.props e scripts/buildsystems/vcpkg.targets em cada .vcxproj. Ao usar caminhos relativos, isso permite que o vcpkg seja consumido como submódulo e obtido automaticamente pelos usuários quando executam git clone.

A maneira mais fácil de adicioná-los a cada projeto em sua solução é criar Directory.Build.props e Directory.Build.targets arquivos na raiz do repositório.

Os exemplos a seguir partem do pressuposto de que estão na raiz do seu repositório, com um submódulo de microsoft/vcpkg em vcpkg.

Exemplo Directory.Build.props

<Project>
 <Import Project="$(MSBuildThisFileDirectory)vcpkg\scripts\buildsystems\msbuild\vcpkg.props" />
</Project>

Exemplo Directory.Build.targets

<Project>
 <Import Project="$(MSBuildThisFileDirectory)vcpkg\scripts\buildsystems\msbuild\vcpkg.targets" />
</Project>

Consulte a seção Personalizar sua compilação da documentação oficial do MSBuild para obter mais informações sobre Directory.Build.targets e Directory.Build.props.

Passe as propriedades do MSBuild para triplets e portfiles.

Você pode passar o valor das propriedades do MSBuild para as compilações do vcpkg como variáveis de ambiente usando a tarefa SetEnv. Você deve definir essas variáveis de ambiente antes da VcpkgTripletSelection tarefa.

O exemplo a seguir mostra um projeto MSBuild passando o valor da propriedade MyProp para o vcpkg como uma variável de ambiente, para torná-lo utilizável em triplets e portfiles.

Exemplo Directory.Build.props

<Project>
  <PropertyGroup>
    <VcpkgRoot>C:\dev\vcpkg\</VcpkgRoot>
    <MyProp Condition="'$(Platform)' == 'x64'">X64_VALUE</MyProp>
    <MyProp Condition="'$(Platform)' == 'x86'">X86_VALUE</MyProp>
  </PropertyGroup>
 <Import Project="$(VcpkgRoot)scripts\buildsystems\msbuild\vcpkg.props" />
</Project>

Exemplo Directory.Build.targets

<Project>
  <Import Project="$(VcpkgRoot)scripts\buildsystems\msbuild\vcpkg.targets" />
  <Target Name="_SetVcpkgEnvVars" BeforeTargets="VcpkgTripletSelection">
    <Message Text="Setting MY_PROP to $(MyProp)" />
    <SetEnv Name="MY_PROP" Value="$(MyProp)" Prefix="false" />
  </Target>
</Project>

Exemplo de trigêmeo x64-windows-custom.cmake

set(VCPKG_TARGET_ARCHITECTURE x64)
set(VCPKG_CRT_LINKAGE dynamic)
set(VCPKG_LIBRARY_LINKAGE dynamic)

# Pass the environment variable to port builds
set(VCPKG_ENV_PASSTHROUGH_UNTRACKED MY_PROP)

Exemplo de portfile.cmake

set(VCPKG_POLICY_EMPTY_PACKAGE enabled)

MESSAGE(STATUS "MY_PROP is $ENV{MY_PROP}")

Pacote NuGet vinculado

Projetos VS também podem ser integrados por meio de um pacote NuGet. Isso modificará o arquivo de projeto, portanto, não recomendamos essa abordagem para projetos código aberto.

PS D:\src\vcpkg> .\vcpkg integrate project
Created nupkg: D:\src\vcpkg\scripts\buildsystems\vcpkg.D.src.vcpkg.1.0.0.nupkg

With a project open, go to Tools->NuGet Package Manager->Package Manager Console and paste:
    Install-Package vcpkg.D.src.vcpkg -Source "D:/src/vcpkg/scripts/buildsystems"

Configuração comum

VcpkgEnabled (Usar Vcpkg)

Isso pode ser definido como "false" para desabilitar explicitamente a integração vcpkg para o projeto

VcpkgConfiguration (Configuração do Vcpkg)

Se os nomes de configuração forem complexos demais para o vcpkg adivinhar corretamente, você poderá atribuir essa propriedade a Release ou Debug para informar explicitamente ao vcpkg qual variante de bibliotecas você deseja usar.

VcpkgEnableManifest (Usar manifesto Vcpkg)

Essa propriedade deve ser definida como true para consumir a partir de um arquivo local vcpkg.json. Se definido como false, todos os arquivos locais vcpkg.json serão ignorados.

Atualmente, o padrão é false, mas no futuro será true.

VcpkgTriplet (Trigêmeo)

Esta propriedade controla o triplet do qual as bibliotecas serão consumidas, como x64-windows-static ou arm64-windows.

Se isso não estiver definido explicitamente, vcpkg deduzirá o trigêmeo correto com base nas configurações de Visual Studio. O vcpkg deduzirá apenas triplets que usam vinculação dinâmica de biblioteca e vinculação dinâmica de CRT; se você quiser dependências estáticas ou usar o CRT estático (/MT), será necessário definir o triplet manualmente.

Você pode ver o trigêmeo deduzido automaticamente definindo a verbosidade do MSBuild como Normal ou superior:

Atalho: Ctrl+Q "compilar e executar"

Ferramentas -> Opções -> Projetos e Soluções -> Compilação e Execução -> Verbosidade da saída de compilação do projeto do MSBuild

Consulte também Triplets

VcpkgHostTriplet (Triplet do Host)

Isso pode ser definido para um triplet personalizado a ser usado para resolver dependências do host.

Se não estiver definido, o padrão será o triplet "nativo" (x64-windows).

Consulte também dependências de host.

VcpkgInstalledDir (Diretório Instalado)

Essa propriedade define o local do qual o vcpkg instalará e consumirá bibliotecas. Use VcpkgManifestInstalledBaseDir em uma solução que usa o modo de manifesto e usa vários trigêmeos.

No modo de manifesto, o padrão é $(VcpkgManifestRoot)\vcpkg_installed\$(VcpkgTriplet)\. No modo clássico, esse padrão é $(VcpkgRoot)\installed\.

VcpkgManifestInstalledBaseDir (Diretório Base instalado)

Ao usar o modo de manifesto na solução que cria vários trigêmeos, a configuração VcpkgInstalledDir pode ser de challanging porque deve ser diferente para projetos que precisam de trigêmeos diferentes.

Nesse caso, pode-se definir VcpkgManifestInstalledBaseDir o que pode ser definido globalmente e é acrescentado pelo nome do trigêmeo.

VcpkgApplocalDeps (Implantar DLLs localmente no aplicativo)

Esta propriedade habilita ou desabilita a detecção e a cópia de DLLs dependentes da árvore de instalação do vcpkg para o diretório de saída do projeto. O padrão é true.

VcpkgXUseBuiltInApplocalDeps (Usar implantação local integrada do aplicativo)

Essa propriedade controla qual implementação de implantação de DLL local do aplicativo vcpkg usa quando VcpkgApplocalDeps está habilitada. O padrão é true, que usa a implementação integrada vcpkg z-applocal. Defina como false para usar a implementação legada do PowerShell applocal.ps1.

Essa propriedade não tem efeito quando $(VcpkgApplocalDeps) é falsa.

Configuração do modo Manifest

Para usar manifestos (vcpkg.json) com o MSBuild, primeiro você precisa usar um dos métodos de integração acima. Em seguida, adicione um vcpkg.json acima do arquivo de projeto (como na raiz do repositório de origem) e defina a propriedade VcpkgEnableManifest como true. Você pode definir essa propriedade no IDE, em Propriedades do Projeto>Vcpkg>Usar manifesto do Vcpkg. Talvez seja necessário recarregar o IDE para ver a Página de Propriedades vcpkg.

vcpkg será executado durante o build do projeto e instalará as dependências listadas ao vcpkg_installed/$(VcpkgTriplet)/ lado do vcpkg.json arquivo; essas bibliotecas serão incluídas automaticamente e vinculadas aos seus projetos do MSBuild.

Problemas conhecidos

• O Visual Studio 2015 não rastreia corretamente as edições nos arquivos vcpkg.json e vcpkg-configuration.json e não responderá às alterações, a menos que um .cpp seja editado.

VcpkgAdditionalInstallOptions (Opções adicionais)

Ao usar um manifesto, esta opção especifica sinalizadores de linha de comando adicionais para passar para a invocação da ferramenta vcpkg subjacente. Isso pode ser usado para acessar recursos que ainda não foram expostos por meio de outra opção.

VcpkgManifestInstall (Instalar dependências do Vcpkg)

Essa propriedade pode ser definida para false para desabilitar a restauração automática de dependências durante a compilação do projeto. As dependências devem ser restauradas manualmente, em separado, via a linha de comando do vcpkg.