Improve Windows build scripts and documentation

[doug-walker]

As mentioned in the Installation guide, there are two .bat scripts available to help install prerequisites and build OCIO on Windows. These are helpful, however, there are some rough edges with these scripts. For example, some of the instructions are not clear about installing vcpkg. Additionally, instructions should be added for using the Community rather than the Enterprise edition of Visual Studio.

This issue is for someone to take a fresh look at installation on Windows, from the point of view of an inexperienced developer, and make some improvements. Some of the improvements could be to the documentation page and some could be in the .bat scripts themselves.

[eaniemey]

Hi Doug, can you assign this one to me please?

[carolalynn]

Hi @eaniemey - Penne Lee had also expressed interest in working on this issue as well - if you're planning on working on it for Dev Days, could you please join the #devdays2023 channel on the OCIO slack instance, and also check in with Penne (I believe you both work at Intel) so that duplicate work is not done? :)

Thanks for your interest in contributing to OCIO!

[eaniemey]

Hi I reached out to Doug already on Slack.

From: Carol Payne @.> Date: Wednesday, October 11, 2023 at 12:09 PM To: AcademySoftwareFoundation/OpenColorIO @.> Cc: Niemeyer, Erik A @.>, Mention @.> Subject: Re: [AcademySoftwareFoundation/OpenColorIO] Improve Windows build scripts and documentation (Issue #1867)

Hi @eaniemeyhttps://github.com/eaniemey - Penne Lee had also expressed interest in working on this issue as well - if you're planning on working on it for Dev Days, could you please join the #devdays2023 channel on the OCIO slack instance, and also check in with Penne (I believe you both work at Intel) so that duplicate work is not done? :)

Thanks for your interest in contributing to OCIO!

— Reply to this email directly, view it on GitHubhttps://github.com/AcademySoftwareFoundation/OpenColorIO/issues/1867#issuecomment-1758215985, or unsubscribehttps://github.com/notifications/unsubscribe-auth/ADHLAXHMMLUSIHGQVNDDRSLX63OGLANCNFSM6AAAAAA5CNGBGA. You are receiving this because you were mentioned.Message ID: @.***>

[carolalynn]

We're happy to have you work on it, I just wanted you to be aware of the possibility of duplicate effort. Penne had stated interest in this issue a few days ago.

[pennelee]

Thanks @carolalynn22 and @doug-walker for making the connection! Great minds... :)

As there are a few of us doing this set up on Windows, we decided we will roll up our feedback to Erik to drive the changes. Thank you!

[carolalynn]

Perfect! Sounds like a great approach. Thank you both!

[doug-walker]

Thank you both, we love the collaboration!

[eaniemey]

Summary: Below are the detailed observations the Intel team (Eli Hernandez, Penne Lee, Erik Niemeyer) made while attempting to get the OCIO build environment setup and building correctly. We would like to use these observations to spawn a discussion and subsequent sub-issues to resolve the problems we ran into.

--

• Documentation issues:
  • (Eli) Observation issue: OCIO build observed link errors out of the yaml-cpp built library
    • Probable cause: The yaml-cpp link errors were most likely caused by missing required components
    • Assumption: It is presumed that missing required component was a result of creating tool chain with the "vcpkg install opencolorio[tools]:x64-windows" command.
    • Solution: using the ocio_deps.bat to setup required tools chain instead initial vcpkg command every component build fine. Note: Created new OCIO configuration environment and a fresh OpenColorIO source repository for the successful build. However, it's believed that built "tool chain" via the ocio_deps.bat command was key to get all required components and achieve a successful build.
    • Feedback: Using ocio_deps.bat is key here and it should be the primary way to setup OCIO for developers! So, feedback is to add to OCIO documentation a note to state that ocio_depts.bat batch command as the primary method to setup for OCIO development on Windows platforms. Might also add cautionary note to state that the "vcpkg install opencolorio[tools]:x64-windows" command might not always setup the correct tool chain ( especially on Windows 11) leading to possible build errors.
  • (Eli) Setup Instructions Flow
  • Improve the flow of instruction to setup for OCIO developers, e.g., state clear step distinction if for Windows, Linux, MacOs, Andriod, etc...
  • There are procedure steps that could lead new contributors to doubt if steps are for Windows or other OS platforms. Specifically on the "Installation" steps.
    • Minimize link hopping by adding more in-line and concise setup steps.
  • (Penne) The second script is called [ocio.bat] - (https://github.com/AcademySoftwareFoundation/OpenColorIO/tree/main/share/dev/windows/ocio.bat) and it provide a way to configure and build OCIO from source. Moreover, this script executes the install step of cmake as well as the unit tests. The main use case is the following:
    • ocio.bat --b --i --vcpkg --ocio --type Release
      • Actually you need to add --configure, but person who is not familiar with cmake may not know that.
• Misc Issues:
  • Debug Windows build seems broken, I got error using ocio.bat with --type Debug
    • LINK : fatal error LNK1104: cannot open file 'freeglutd.lib' for ociolutimage.exe, ocioarchive.exe, test_utils_exec.exe etc.
    • Also not sure if it is obvious, but I think they do not use the Visual Studio "Debug" mode for the Release build and need to call ocio.bat again to re-make the Debug project.
  • (Erik) There is no Windows-based docker package to ease build environment setup like there is on Linux.
  • (Erik) Not well tested against a variety of Visual Studio versions
  • (Erik) No support for Clang or ICX compilers
    • (Erik) No support for selecting dynamic or static library output

[doug-walker]

Many thanks to the Intel team for the helpful notes about problems with the build system! The next step would be for someone to take those suggestions and make a PR with some improvements.