protobuf source v3.21.12

This directory contains *CMake* files that can be used to build protobuf with *MSVC* on *Windows*. You can build the project from *Command Prompt* and using an *Visual Studio* IDE. You need to have [CMake](http://www.cmake.org), [Visual Studio](https://www.visualstudio.com) and optionally [Git](http://git-scm.com) installed on your computer before proceeding. Most of the instructions will be given to the *小ommand Prompt*, but the same actions can be performed using appropriate GUI tools. Environment Setup ================= Open the appropriate *Command Prompt* from the *Start* menu. For example *x86 Native Tools Command Prompt for VS 2019*: C:\Program Files (x86)\Microsoft Visual Studio\2019\Professional> Change to your working directory: C:\Program Files (x86)\Microsoft Visual Studio\2019\Professional>cd C:\Path\to C:\Path\to> Where *C:\Path\to* is path to your real working directory. Create a folder where protobuf headers/libraries/binaries will be installed after built: C:\Path\to>mkdir install If *cmake* command is not available from *Command Prompt*, add it to system *PATH* variable: C:\Path\to>set PATH=%PATH%;C:\Program Files (x86)\CMake\bin If *git* command is not available from *Command Prompt*, add it to system *PATH* variable: C:\Path\to>set PATH=%PATH%;C:\Program Files\Git\cmd Optionally, you will want to download [ninja](https://ninja-build.org/) and add it to your *PATH* variable. C:\Path\to>set PATH=%PATH%;C:\tools\ninja Good. Now you are ready to continue. Getting Sources =============== You can get the latest stable source packages from the release page: https://github.com/protocolbuffers/protobuf/releases/latest For example: if you only need C++, download `protobuf-cpp-[VERSION].tar.gz`; if you need C++ and Java, download `protobuf-java-[VERSION].tar.gz` (every package contains C++ source already); if you need C++ and multiple other languages, download `protobuf-all-[VERSION].tar.gz`. Or you can use git to clone from protobuf git repository. C:\Path\to> mkdir src & cd src C:\Path\to\src> git clone -b [release_tag] https://github.com/protocolbuffers/protobuf.git Where *[release_tag]* is a git tag like *v3.0.0-beta-1* or a branch name like *main* if you want to get the latest code. Go to the project folder: C:\Path\to\src> cd protobuf C:\Path\to\src\protobuf> Remember to update any submodules if you are using git clone (you can skip this step if you are using a release .tar.gz or .zip package): ```console C:\Path\to\src\protobuf> git submodule update --init --recursive ``` Good. Now you are ready for *CMake* configuration. CMake Configuration =================== *CMake* supports a lot of different [generators](http://www.cmake.org/cmake/help/latest/manual/cmake-generators.7.html) for various native build systems. Of most interest to Windows programmers are the following: * [Makefile](http://www.cmake.org/cmake/help/latest/manual/cmake-generators.7.html#makefile-generators). This generates NMake Makefiles for Visual Studio. These work, but they are rather slow. * [Visual Studio](http://www.cmake.org/cmake/help/latest/manual/cmake-generators.7.html#visual-studio-generators) This generates a Visual Studio solution for the project. * [Ninja](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#ninja-generator) This uses the external tool [Ninja](https://ninja-build.org/) to build. It is the fastest solution available. Note that as of Visual Studio 2015, Visual Studio includes [support for opening directly CMake-based projects](https://docs.microsoft.com/en-us/cpp/build/cmake-projects-in-visual-studio). It is considered good practice not to build CMake projects in the source tree but in a separate folder. Create a temporary *build* folder and change your working directory to it: mkdir C:\Path\to\build\protobuf cd C:\Path\to\build\protobuf C:\Path\to\build\protobuf> The *Makefile* and *Ninja* generators can build the project in only one configuration, so you need to build a separate folder for each configuration. To start using a *Release* configuration via the *NMmake* generator: C:\Path\to\build\protobuf>mkdir release & cd release C:\Path\to\build\protobuf\release>cmake -G "NMake Makefiles" ^ -DCMAKE_BUILD_TYPE=Release ^ -DCMAKE_INSTALL_PREFIX=C:\Path\to\install ^ C:\Path\to\src\protobuf It will generate a *NMake* *Makefile* in the current directory. To use *Debug* configuration using *Ninja*: C:\Path\to\build\protobuf>mkdir debug & cd debug C:\Path\to\build\protobuf\debug>cmake -G "Ninja" ^ -DCMAKE_BUILD_TYPE=Debug ^ -DCMAKE_INSTALL_PREFIX=C:\Path\to\install ^ C:\Path\to\src\protobuf It will generate *Ninja* build scripts in current directory. The *Visual Studio* generator is multi-configuration: it will generate a single *.sln* file that can be used for both *Debug* and *Release*: C:\Path\to\build\protobuf>mkdir solution & cd solution C:\Path\to\build\protobuf\solution>cmake -G "Visual Studio 16 2019" ^ -DCMAKE_INSTALL_PREFIX=C:\Path\to\install ^ C:\Path\to\src\protobuf It will generate *Visual Studio* solution file *protobuf.sln* in current directory. Unit Tests ---------- Unit tests are being built along with the rest of protobuf. The unit tests require Google Mock (now a part of Google Test). A copy of [Google Test](https://github.com/google/googletest) is included as a Git submodule in the `third-party/googletest` folder. (You do need to initialize the Git submodules as explained above.) Alternately, you may want to use protobuf in a larger set-up, you may want to use that standard CMake approach where you build and install a shared copy of Google Test. After you've built and installed your Google Test copy, you need add the following definition to your *cmake* command line during the configuration step: `-Dprotobuf_USE_EXTERNAL_GTEST=ON`. This will cause the standard CMake `find_package(GTest REQUIRED)` to be used. [find_package](https://cmake.org/cmake/help/latest/command/find_package.html) will search in a default location, which on Windows is *C:\Program Files*. This is most likely not what you want. You will want instead to search for Google Test in your project's root directory (i.e. the same directory you've passed to `CMAKE_INSTALL_PREFIX` when building Google Test). For this, you need to set the `CMAKE_PREFIX_PATH` CMake variable. (There are other ways in CMake, see the [manual](https://cmake.org/cmake/help/latest/command/find_package.html) for details.) For example: C:\Path\to\build\protobuf>mkdir solution & cd solution C:\Path\to\build\protobuf\solution>cmake -G "Visual Studio 16 2019" ^ -DCMAKE_INSTALL_PREFIX=C:\Path\to\install ^ -DCMAKE_PREFIX_PATH=C:\Path\to\my_big_project ^ -Dprotobuf_USE_EXTERNAL_GTEST=ON ^ C:\Path\to\src\protobuf In most cases, `CMAKE_PREFIX_PATH` and `CMAKE_INSTALL_PREFIX` will point to the same directory. To disable testing completely, you need to add the following argument to you *cmake* command line: `-Dprotobuf_BUILD_TESTS=OFF`. For example: C:\Path\to\build\protobuf\solution>cmake -G "Visual Studio 16 2019" ^ -DCMAKE_INSTALL_PREFIX=C:\Path\to\install ^ -Dprotobuf_BUILD_TESTS=OFF ^ C:\Path\to\src\protobuf Compiling ========= The standard way to compile a *CMake* project is `cmake --build <directory>`. Note that if your generator supports multiple configurations, you will probably want to specify which one to build: cmake --build C:\Path\to\build\protobuf\solution --config Release You can also run directly the build tool you've configured: C:\Path\to\build\protobuf\release>nmake or C:\Path\to\build\protobuf\debug>ninja And wait for the compilation to finish. If you prefer to use the IDE: * Open the generated protobuf.sln file in Microsoft Visual Studio. * Choose "Debug" or "Release" configuration a