Instalação personalizada: desenvolvendo as bibliotecas de drivers C a partir da origem

Esta página detalha como baixar, descompactar, configurar e construir as bibliotecas do libbson e libmongoc a partir de seu código-fonte.

Dica

Informações adicionais

Admoestações (como esta) contêm informações extras e detalhes explicativos que não são necessários para concluir o tutorial, mas podem ser úteis para leitores atentos e usuários mais avançados que desejam uma explicação do significado de determinadas etapas do tutorial.

A seguinte página utiliza algumas variáveis nomeadas para representar informações de configuração, como $VERSION. Você deve escolher valores para essas variáveis antes de iniciar o tutorial. Quando você vir uma variável referenciada em uma etapa do tutorial, substitua seu valor em seu lugar.

Dica

Antes de construir as bibliotecas, verifique se você está executando em uma plataforma compatível. Para obter a lista de plataformas suportadas, consulte a página de compatibilidade.

Escolha uma versão

Antes de começar, saiba qual versão do mongo-c-driver você estará baixando. Uma lista de versões disponíveis pode ser encontrada na página de tags de repositório do GitHub. Este tutorial documenta a versão atual do driver,1 3010v...

Para o restante desta página, $VERSION fará referência ao número da versão do mongo-c-driver que você construirá para este tutorial.

Obtendo a fonte

Obtenha o código-fonte mongo-c-driver de uma das seguintes maneiras:

Clone o repositório usando git (recomendado). Para obter mais informações,consulte Baixando usando Git.
Baixe um arquivo de origem em uma versão específica. Para obter mais informações, consulte Baixando um Arquivo de versão.

Importante

É altamente recomendável que novos usuários usem uma versão estável do driver, em vez de criar a partir de uma ramificação de desenvolvimento. Ao git clone ou baixar um arquivo do repositório, certifique-se de especificar uma tag de versão (por exemplo, com o argumento --branch do Git).

Baixando usando Git

Você pode clonar o repositório do driver C do GitHub usando o Git. As tags Git para versões lançadas recebem o nome da versão à qual correspondem (por exemplo, "..1 3010"). Para clonar o repositório a partir da linha de comando, use o seguinte comando:

$ git clone https://github.com/mongodb/mongo-c-driver.git --branch="$VERSION" "$SOURCE"

Dica

Apesar do nome, você pode usar a opção --branch do comando git-clone para clonar a partir de marcações de repositório.

Baixando um arquivo de versão

You can obtain an archived snapshot of the C driver repository from the repository's Releases page. Every release includes a mongo-c-driver-x.y.z.tar.gz archive, which contains the minimal set of files that you'll need for the build.

## Download using wget:
$ wget "https://github.com/mongodb/mongo-c-driver/archive/refs/tags/$VERSION.tar.gz" \
     --output-document="mongo-c-driver-$VERSION.tar.gz"
## Extract using tar:
$ tar xf "mongo-c-driver-$VERSION.tar.gz"

Os comandos anteriores criam o diretório mongo-c-driver-$VERSION dentro do diretório em que você os executou, que é a raiz da árvore de origem do driver. Esta documentação refere-se a este diretório como $SOURCE. O diretório $SOURCE contém o arquivo CMakeLists.txt de nível superior.

## Using curl:
$ curl "https://github.com/mongodb/mongo-c-driver/archive/refs/tags/$VERSION.tar.gz" \
     --output="mongo-c-driver-$VERSION.tar.gz"
## Extract using tar:
$ tar xf "mongo-c-driver-$VERSION.tar.gz"

## Use Invoke-WebRequest:
PS> $url = "https://github.com/mongodb/mongo-c-driver/archive/refs/tags/$VERSION.zip"
PS> $file = "mongo-c-driver-$VERSION.zip"
PS> Invoke-WebRequest -UseBasicParsing -Uri $url -OutFile $file
## Extract using Expand-Archive:
PS> Expand-Archive mongo-c-driver-$VERSION.zip

Os comandos anteriores criam o diretório mongo-c-driver-$VERSION dentro do diretório em que você os executou. O diretório mongo-c-driver-$VERSION contém um segundo diretório mongo-c-driver-$VERSION, que é a raiz da árvore de origem do driver. Esta documentação refere-se a este diretório como $SOURCE. O diretório $SOURCE contém o arquivo CMakeLists.txt de nível superior.

Obtenção de pré-requisitos

You must install CMake to configure the libmongoc and libbson projects. We highly recommended that you download the latest stable version of CMake that is available for your platform.

Selecione a aba correspondente ao seu sistema operacional e siga as instruções para baixar o CMake:

Visite a página para baixar do CMake.
Baixe o arquivo CMake .msi ou .dmg e utilize-o para instalar o CMake.

Visite a página de downloads do CMake
Baixe o script de shell de extração automática, que termina com .sh.
Execute o script usando o utilitário sh e passando os argumentos apropriados para executar a instalação. Por exemplo, com o CMake 3.27.0 na plataforma x86_64, execute o seguinte comando:
sh cmake-3.27.0-linux-x86_64.sh --prefix="$HOME/.local" --exclude-subdir --skip-license
Supondo que $HOME/.local/bin esteja na sua lista $PATH , o comando cmake para 3.27.0 ficará disponível.

A opção --help pode ser passada para o script de shell para obter mais informações.

Esta página pressupõe que cmake está disponível como um comando em sua variável de ambiente do PATH e pode ser executado como "cmake" a partir de uma shell. Você pode testar isso solicitando o --version do CMake a partir da linha de comando, conforme mostrado no código a seguir:

 cmake --version
 cmake version 3.21.4
CMake suite maintained and supported by Kitware (kitware.com/cmake).

Observação

Se você pretende construir somente o libbson , então o CMake será suficiente para a construção. Recursos adicionais do driver C podem exigir a instalação de dependências externas adicionais, mas não nos preocuparemos com eles aqui.

Configuração para libbson

Importante

Se você estiver construindo com Xcode [1] ou Visual Studio [2], talvez seja necessário executar o CMake de dentro de um ambiente especial no qual a respectiva cadeia de ferramentas está disponível.

Que o nome $BUILD seja o caminho $SOURCE/_build. Este será o diretório onde nossos arquivos construídos serão escritos pelo CMake.

Com o diretório de origem para mongo-c-driver em $SOURCE e o diretório de compilação $BUILD, o seguinte comando pode ser executado a partir de uma linha de comando para configurar o projeto com libbson e libmongoc:

$ cmake -S $SOURCE -B $BUILD \
   -D ENABLE_EXTRA_ALIGNMENT=OFF \
   -D ENABLE_AUTOMATIC_INIT_AND_CLEANUP=OFF \
   -D CMAKE_BUILD_TYPE=RelWithDebInfo \
   -D BUILD_VERSION="$VERSION" \
   -D ENABLE_MONGOC=OFF

Se todas as dependências estiverem satisfeitas, o comando acima deverá ser bem-sucedido e terminar com:

$ cmake …
## … (Lines of output) …
-- Generating done
-- Build files have been written to: $BUILD

Se a configuração falhar com um erro, consulte a saída do CMake para obter mensagens de erro e informações. Certifique-se de que a configuração seja bem-sucedida antes de continuar.

Dica

O que esses argumentos do CMake significam?

O BUILD_VERSION define o número da versão que será incluído nos resultados da compilação. Isso deve ser definido para o mesmo valor que a versão do driver de origem que foi baixado em Obter a fonte.

O ENABLE_EXTRA_ALIGNMENT e o ENABLE_AUTOMATIC_INIT_AND_CLEANUP fazem parte do mongo-c-driver e correspondem a funcionalidades obsoletas que são habilitadas somente por padrão para fins de compatibilidade com a ABI. É altamente recomendável desativar esses recursos sempre que possível.

O argumento ENABLE_MONGOC=OFF desabilitou a construção libmongoc. Veremos isso na próxima seção.

The CMAKE_BUILD_TYPE setting tells CMake what variant of code will be generated. In the case of RelWithDebInfo, optimized binaries will be produced, but still include debug information. The CMAKE_BUILD_TYPE has no effect on Multi-Config generators (i.e. Visual Studio), which instead rely on the --config option when building/installing.

Construindo o projeto

Depois de configurar com êxito o projeto, a compilação pode ser executada usando o CMake:

$ cmake --build $BUILD --config RelWithDebInfo --parallel

Se configurado corretamente e todas as dependências estiverem satisfeitas, o comando acima deve continuar para compilar e vincular os componentes configurados. Se o comando acima falhar, é provável que haja um erro com seu ambiente ou você esteja usando uma plataforma não suportada/não testada. Consulte a saída da ferramenta de construção para obter mais informações.

Dica

A opção --config

A opção --config é usada para definir a configuração de compilação a ser usada no caso de geradores de configuração múltipla (ou seja, Visual Studio). Não tem efeito sobre outros geradores, que em vez disso usam CMAKE_BUILD_TYPE.

Instalando os resultados construídos

Seja $PREFIX o caminho $SOURCE/_install. Podemos usar o CMake para instalar os resultados da construção:

$ cmake --install "$BUILD" --prefix "$PREFIX" --config RelWithDebInfo

Este comando instalará os mongo-c-driver resultados da compilação do no $PREFIX diretório .

Dica

A opção --config

A opção --config é usada apenas para geradores de várias configurações (ou seja, Visual Studio) e é ignorado. O valor fornecido para --config deve ser o mesmo que foi fornecido para --config com cmake --build.

Dica

Gerenciando versões da biblioteca

A instalação do Driver MongoDB C a partir da origem ou usando um gerenciador de pacote instala arquivos que usam nomes e caminhos com controle de versão. Para evitar a necessidade de atualizar sua configuração de compilação ao atualizar o driver, você pode usar os mecanismos de descoberta de dependência padrão do sistema de compilação, como o comando find_package() do CMake. Você também pode usar as convenções de symlink da biblioteca compartilhada da sua plataforma em vez de codificar nomes de arquivos de bibliotecas completas ou caminhos de instalação.

Configuração com libmongoc

If you followed the above steps starting from Configuring for libbson, your final result with only contain libbson and not the full C database driver library. Building of libmongoc is enabled/disabled using the ENABLE_MONGOC CMake variable. Re-run CMake again, but set ENABLE_MONGOC to TRUE:

$ cmake -D ENABLE_MONGOC=ON -B $BUILD -S $SOURCE

If the above command succeeds, then the project has been reconfigured to build with libmongoc. Follow the process at Building the Project and Installing the Built Results again to build and install libmongoc.

Notas de rodapé

[1]

Se você deseja configurar e construir o projeto com o Xcode, as ferramentas de linha de comando do Xcode precisam ser instaladas e disponibilizadas no ambiente. Em um ambiente de linha de comando, execute:

$ xcode-select --install

Isso garantirá que os compiladores e vinculadores estejam disponíveis em seu $PATH.

[2]

Se você quiser configurar e criar o projeto usando o Microsoft Visual C++, as ferramentas e variáveis de ambiente do Visual C++ podem precisar ser definidas ao executar qualquer comando CMake ou de criação.

In many cases, CMake will detect a Visual Studio installation and automatically load the environment itself when it is executed. This automatic detection can be controlled with CMake's -G, -T, and -A options. The -G option is the most significant, as it selects which Visual Studio version will be used. The versions of Visual Studio supported depends on the version of CMake that you have installed. A list of supported Visual Studio versions can be found here.

Para maior controle e mais opções de ferramentas, é recomendável executar comandos de dentro de um PowerShell do desenvolvedor do Visual Studio (preferencial) ou Prompt de comando do desenvolvedor (legado).

For more information, refer to: Visual Studio Developer Command Prompt and Developer PowerShell and Use the Microsoft C++ toolset from the command line on the Microsoft Visual Studio documentation pages.

Voltar

Começar

Conecte-se ao MongoDB