Documentation: Install protobuf with vcpkg

[jdsika]

I tried to follow the Windows instructions using vcpkg: https://opensimulationinterface.github.io/osi-antora-generator/asamosi/latest/interface/setup/installing_prerequisites.html#_windows

Trying to figure out how to pin the protobuf version using vcpkg is kind of a joke if you read this. Maybe we can place a hint in the documentation?

[PhRosenberger]

I tried to follow the Windows instructions using vcpkg: https://opensimulationinterface.github.io/osi-antora-generator/asamosi/latest/interface/setup/installing_prerequisites.html#_windows

Trying to figure out how to pin the protobuf version using vcpkg is kind of a joke if you read this. Maybe we can place a hint in the documentation?

Oh yes, pinning a version in vcpkg seems to be a bigger task than one would expect. I would also vote for a hint.

[PhRosenberger]

At least I now found out how to build protobuf in the version I want it to be.

You need a json file called vcpkg.json with the following content:

{
  "dependencies": [
    "protobuf"
  ],
  "overrides": [
    {
      "name": "protobuf",
      "version": "3.21.12"
    }
  ],
  "builtin-baseline": "53bef8994c541b6561884a8395ea35715ece75db"
}

and then run vcpkg with <path-to-vcpkg>\vcpkg.exe --triplet=x64-windows-static-md --feature-flags="versions" install protobuf

of cause, the triplet from the OSI build instructions is needed and called here and additionally the version-option that let's it
look for the json file.

[PhRosenberger]

At least I now found out how to build protobuf in the version I want it to be.

You need a json file called vcpkg.json with the following content:

{
  "dependencies": [
    "protobuf"
  ],
  "overrides": [
    {
      "name": "protobuf",
      "version": "3.21.12"
    }
  ],
  "builtin-baseline": "53bef8994c541b6561884a8395ea35715ece75db"
}

and then run vcpkg with <path-to-vcpkg>\vcpkg.exe --triplet=x64-windows-static-md --feature-flags="versions" install protobuf

of cause, the triplet from the OSI build instructions is needed and called here and additionally the version-option that let's it look for the json file.

However it creates a folder called vcpkg_installed that does not help me with building OSI, @jdsika do you know how to proceed then?

[jdsika]

"builtin-baseline": "53bef8994c541b6561884a8395ea35715ece75db"

Where is this coming from? :D

I mean I would give an individual installation path (the same that protobuffer docs recommend) and add the bin folder to PATH?

[PhRosenberger]

"builtin-baseline": "53bef8994c541b6561884a8395ea35715ece75db"

Where is this coming from? :D

The baseline here is the latest release of vcpkg / its commit number.

[PhRosenberger]

I mean I would give an individual installation path (the same that protobuffer docs recommend) and add the bin folder to PATH?

Ok so let's give it a try and then add these steps to the build instructions, if it does the trick, right?

[PhRosenberger]

@jdsika isn't #632 somehow related to this?

[PhRosenberger]

Probably also #569 ?

[pmai]

It seems unclear to me that we even want to venture into this whole topic: The vcpkg instructions are there so that you easily can get any version of protobuf installed and then try out OSI etc. In that case you never want to pin anything, so why bother with all of this complexity?

When you want to pin something you are setting up a project, and hence maintaining dependencies, etc. If - and that's a big if - you want to use vcpkg in that case, you should be using its manifest mode, and there is lots of documentation in doing this, so no OSI specifics. And there are tons of other ways of handling dependencies, including building your own version from git, as we are doing in our workflows, or treating protobuf as a submodule, or ...

I fail to see why providing guidance on how to manage C++ project development on Windows falls within our tasks... We also do not provide any pinning and setup information for Linux that goes beyond maybe use apt to install protobuf, which usually is not the way you would handle project development, but works for trying out OSI. Same as using vcpkg on Windows.

[jdsika]

:) I call you for that Pierre. But @PhRosenberger thanks for finding related issues and yes they are related but not the same but obviously tell a story of more people being interested in this topic

[jdsika]

Only Linux mentions a minimum requirement of proto 3.0.0:
https://opensimulationinterface.github.io/osi-antora-generator/asamosi/latest/interface/setup/installing_prerequisites.html#_linux

[PhRosenberger]

@pmai IMHO we should give a hint how to install OSI with vcpkg, as with the instructions for Linux.
@jdsika I propose to add the following instructions for Paython on Windows:

1. Create a folder for protobuf in a location you like (later: ).
2. Create a new manifest file called vcpkg.json in this folder. with the following content (for more information on baseline see here):

{
  "dependencies": [
    "protobuf"
  ],
  "overrides": [
    {
      "name": "protobuf",
      "version": "<version>"
    }
  ],
  "builtin-baseline": "<vcpkg-commit-no>"
}

3. Execute vcpkg in this folder from a terminal with <path-to-vcpkg>\vcpkg.exe --triplet=x64-windows-static-md --feature-flags="versions" install
4. Go to the folder where you cloned OSI into.
5. Build OSI for python with the following commands in a terminal:

set PROTOC=<path-to-protobuf>\vcpkg_installed\x64-windows-static-md\tools\protobuf\protoc.exe
python setup.by build

6. Hint: If you have a Python version that does not have the distutils package anymore, try installing setuptools instead with pip install setuptools

Can you please try and comment and then I volunteer for making a PR:-)

[jdsika]

@PhRosenberger In general yes, I think we should give a hint. Specifically the point 5. could be painful if you sync with Clemens if we consider the different protobuffer versions.
This is also what Pierre is mentioning. Putting things into the documentation means that the maintainer take over responsibility for it. Should OSI be the place where to put instructions on how to setup projects... no.... BUT in our case we would profit from the instructions e.g. regarding one particular version of protobuffer. e.g. the one we pin in our CI- workflow as THIS is used for a project related to osi (osi-validation) in oder to use the validator on linux and windows. This somehow gives a justification to spent the effort.
Your PR should make the boundaries very clear:

1. this example shows the pinning of the version in the CI
2. other protobuffer versions may have other instructions (please look further here)
3. this can be used to build/use the osi-validation tool with a specific version
4. do NOT build step 5. yourself but use PIP and the setup.py script from osi to download the right version via the package manager (see Support more protobuf versions in GitHub workflow #766 )
5. This is only about the protoc compiler
6. make sure you mention that protobuffer > 2.6.1 is necessary for OSI and you can use osi in combination with any of the versions in your project BUT
7. the team obviously recommends a newer version to start with (the one pinned in the CI)
8. please users get also some ideas on installing this by looking into the ci workflow

Keep information minimal, correct and sufficient for the task. "get it running with a consistent version of protobuffer with a project like e.g. osi-validation that uses osi as a submodule"

[PhRosenberger]

I guess, we can close this now, as we have #800, right?