Merge pull request #229 from gojimmypi/pr-realm-vs2022

Introduce realm-core Visual Studio 2022 projects

Author: jpbland1

.gitignore

@@ -110,4 +110,67 @@ openssh/regress/authorized_keys*
 stunnel/example/echoserver/echoserver*
 *.plist
 server_err.log
-/.vs
+
+# Visual Studio
+**/.vs
+
+# All backup files
+*.bak
+
+# CMake files to exclude
+/realm/VS2022/**/CMakeCache.txt
+/realm/VS2022/**/*.cmake
+
+/realm/VS2022/**/install_manifest_devel.txt
+/realm/VS2022/**/build/wolfssl
+
+
+# Download by build process:
+/realm/VS2022/zlib/**
+
+/realm/VS2022/**/*.log
+
+# Build-time cache
+/realm/VS2022/**/THIS_WOLFSSL_ROOT_REG.txt
+/realm/VS2022/CMakeFiles/**/*
+/realm/VS2022/test/DebugSync_**
+/realm/VS2022/test/*.lock
+/realm/VS2022/test/*.realm
+/realm/VS2022/test/*.backup-log
+/realm/VS2022/**/*.realm.lock
+/realm/VS2022/**/generate.stamp
+/realm/VS2022/**/generate.stamp.depend
+/realm/VS2022/external/catch/src/Catch2.dir/**/objects.txt
+
+# Realm build-time generated test files
+/realm/VS2022/Testing/**/CTestCheckpoint.txt
+/realm/VS2022/Testing/**/LastTest.log.tmp
+/realm/VS2022/test/benchmark-common-tasks/Debugbenchmark_common_tasks_EmptyCommit_Full_EncryptionOff.realm
+/realm/VS2022/test/benchmark-common-tasks/Debugbenchmark_common_tasks_AddTable_Full_EncryptionOff.realm
+/realm/VS2022/test/benchmark-common-tasks/Debugbenchmark_common_tasks_AddTable_Full_EncryptionOff.realm.lock
+/realm/VS2022/test/DebugLangBindHelper_CompactLargeEncryptedFile.1.path.realm.tmp_compaction_space
+/realm/VS2022/test/DebugShared_CompactEmpty.1.path.realm.tmp_compaction_space
+/realm/VS2022/test/DebugFile_Offset.*
+
+# Realm test-time generated files
+/realm/VS2022/test/**/data.realm
+/realm/VS2022/test/**/Debug**.realm
+/realm/VS2022/test/**/Debugresults.*
+/realm/VS2022/test/**/Debugresults.latest.json
+/realm/VS2022/test/**/*.tmp_compaction_space
+/realm/VS2022/test/**/Debugresults.*.csv
+
+# Realm auto-generated dependency files
+/realm/VS2022/_deps/libuv-build/CMakeFiles
+/realm/VS2022/_deps/libuv-build/Testing
+/realm/VS2022/_deps/libuv-build/DartConfiguration.tcl
+
+/realm/VS2022/_deps/libuv-subbuild/CMakeLists.txt
+/realm/VS2022/_deps/libuv-subbuild/CMakeFiles
+/realm/VS2022/_deps/libuv-subbuild/libuv-populate-prefix/tmp
+/realm/VS2022/_deps/libuv-subbuild/libuv-populate-prefix/src
+
+# Ensure a couple of placeholder files are always included
+!/realm/VS2022/CMakeFiles/VerifyGlobs.cmake
+!/realm/VS2022/CMakeFiles/cmake.verify_globs
+

realm/CMakeLists.txt

@@ -0,0 +1 @@
+message(STATUS "wolfSSL OSP Realm CMake")

realm/README.md

@@ -15,7 +15,7 @@ The [build_wolfssl_with_realm.sh](./build_wolfssl_with_realm.sh) script can be u
 * `-t` use tarball, not git
 * `-u` use $USER name suffix for repository
 
-###
+### Notes
 
 Defaults are to clone [wolfSSL](https://github.com/wolfSSL/wolfssl) and [realm-core](https://github.com/realm/realm-core) to local directory.
 
@@ -44,6 +44,12 @@ BUILD_WOLFSSL=false
 INSTALL_WOLFSSL=false
 ```
 
+Example:
+
+```bash
+cmake -B build -DREALM_INCLUDE_CERTS=1 -DREALM_ENABLE_ENCRYPTION=1 -DREALM_ENABLE_SYNC=1 -DREALM_HAVE_WOLFSSL=1 -DREALM_WOLFSSL_ROOT_DIR=/home/gojimmypi/wolfssl-install-dir
+```
+
 ## Linux manual build: Build wolfSSL
 
 These commands are wrapped in the `build_wolfssl_with_realm.sh` script, mentioned above:
@@ -77,16 +83,141 @@ cmake --build build
 ./build/test/realm-tests
 ```
 
-You can also use the build_wolfssl_with_realm.sh script after adjusting the global variables as needed.
+You can also use the `build_wolfssl_with_realm.sh [-u]` script after adjusting the global variables as needed.
+
+## Visual Studio
+
+To fetch files for a Visual Studio build:
+
+```
+#!/bin/bash
+
+# wolfSSL OSP
+git clone https://github.com/gojimmypi/osp.git
+cd osp
+git checkout dev
+git submodule update --init --recursive
+
+# realm-core is part of wolfssl osp/realm
+cd realm
+git clone https://github.com/gojimmypi/realm-core.git
+
+# If not cloned to osp/realm/realm-core,
+# Edit REALM_DIR_TEMP and REALM_CORE_ROOT values in
+#   [workspace]/osp/realm/VS2022/realm-core-GlobalProperties.props
+
+cd realm-core
+git checkout dev
+git submodule update --init --recursive
+```
+
+The main Ream-Core solution file is located in `VS2022\RealmCore.sln`.
+
+There's also a stand-alone wolfSSH solution that contains only the wolfSSL project in `VS2022\wolfssl-VS2022-cmake.sln`
+
+The platform and machine independent settings such as `$(CurrentVsInstallRoot)` will likely be reset to fully-qualified paths at build time.
+
+See the `vs_clean.sh` to reset variables such as Visual Studio Edition paths to `$(CurrentVsInstallRoot)`.
+
+If no other changes have made, the project `*.vcxproj` changes can also be reverted. Builds should be successful with either full paths or VS macros.
+
+The project files assume there are already source code directories available. For instance:
+
+```
+cd \workspace
+git clone https://github.com/wolfSSL/wolfssl.git   [wolfssl-%USERNAME%]
+git clone https://github.com/wolfSSL/osp.git       [osp-%USERNAME%]
+
+cd [osp-%USERNAME%]
+git clone https://github.com/realm/realm-core.git  [realm-core-%USERNAME%]
+```
+
+Resulting in directories like this (user suffixes optional, but must be consistent):
+
+```
+C:\workspace\wolfssl[-%USERNAME%]
+C:\workspace\osp[-%USERNAME%]
+C:\workspace\osp[-%USERNAME%]\realm-core[-%USERNAME%]
+```
+
+The patch must be applied:
+
+```
+cd C:\workspace\realm-core
+git apply ../osp-gojimmypi/realm/realm-commit-a5e87a39.patch
+```
+
+There's an enclosed WSL script called [build_wolfssl_with_realm.sh](./build_wolfssl_with_realm.sh) that automates installation.
+
+## Clean from DOS Prompt or Visual Studio Developer Command Prompt
+
+Run the enclosed `clean_realm.bat` in the `osp[-%USERNAME%]/realm` directory to delete all build-time generated files:
+
+```
+cd realm
+.\clean_realm.bat
+```
+
+Optionally clean in quiet mode with `/Q` parameter:
+
+```
+cd realm
+.\clean_realm.bat /Q
+```
+
+## Build from Visual Studio Developer Command Prompt
+
+Start a Developer Command Prompt for VS 2022
+
+```
+cd C:\workspace\osp-%USERNAME%\realm\VS2022
+msbuild .\wolfssl-VS2022-cmake.vcxproj /p:Configuration=Debug /p:Platform=x64
+msbuild .\ALL_BUILD.vcxproj /p:Configuration=Debug /p:Platform=x64
+```
+
+## Known Visual Studio Issues
+
+Project files were designed with Visual Studio 2022 version 17.11.5.
+
+Some minor issues are known:
+
+### Project Reload Path Replacements
+
+Occasionally the project files may spontaneously reload, replacing all parameterized values with current fixed paths.
+
+This should be fine for typical end-users, but is highly undesired for developers wishing to contribute changes to project files.
+
+There's no known solution at this time. Undo all changes in the `VS2022` directories, in particular for `.vscproj` and `.filters` files.
+
+Consider performing a full, brute-force clean with `clean_realm.bat`.
+
+For more information see [dotnet/msbuild #5486](https://github.com/dotnet/msbuild/issues/5486) and [Visual Studio Developer Community](https://developercommunity.visualstudio.com/t/NETSdk-build-runs-unexpectedly-undesir/10816622?).
+
+After the initial undo of changes, the reload typically does not occur again.
+
+This issue seems to be related to the `VS2022/CMakeFiles/VerifyGlobs.cmake` file (see below).
+
+# Extra VerifyGlobs.cmake file in CMakeFiles
+
+There's a `VerifyGlobs.cmake` placeholder file located in `[osp]\realm\VS2022\CMakeFiles` that is required for fresh clones to build properly.
+
+### Maximum Path Length
+
+The default Windows configuration has a maximum 256 character path limitation.
+See [Microsoft Learn](https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation?tabs=registry) for more details.
+
+###  VerifyGlobs.cmake Placeholder
+
+Without the `VS2022/CMakeFiles/VerifyGlobs.cmake` file, the initial project build fails due to this auto-generated file being "missing".
+
+Subsequent build attempts are typically successful. Not that _including_ this file also seems to be related to the undesired Project Reload (see above).
 
 ## Generating a new Realm-core patch file:
 
 To generate a new patch compare a particular commit (a5e87a39) to your fork/branch (`dev`):
 
 Save the generated file from this link to the `realm-commit-a5e87a39.patch` file:
 
-
-
 ```
 https://github.com/gojimmypi/realm-core/compare/a5e87a39...dev.patch
 
@@ -99,19 +230,41 @@ Do *not* edit the patch file for tailing spaces, etc. It must be saved exactly a
 
 ## Troubleshooting
 
+### Unexpected value of WOLFSSL_ROOT
+
+Check system and user environment settings.
+
+```powershell
+Get-ChildItem Env:WOLFSSL_ROOT
+```
+
+Check registry, particularly if you use `SETX`:
+
+* User-specific: `HKEY_CURRENT_USER\Environment`
+* System-wide: `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Environment`
+
+Check any other parent processes, startup scripts, Group Policy, etc.
+
+If the registry value continues to be undesirably cached, try one or more of these options:
+
+* Use `SET` and `SETX` to update the value.
+* Log out and back in.
+* Restart Windows Explorer from Task Manager.
+* Reboot.
+
 ### Confirming build with wolfSSL
 
 See generated `config.h` files:
 
 For Linux compile: `build` directory:
 ```
-[wolfssl osp root]\realm\realm-core\build\src\realm\util
+[wolfssl osp root]\realm\realm-core[-username]\build\src\realm\util
 ```
 
 For Visual Studio compile: `out` directory, plus build configuration (e.g. `build\x64-Debug`):
 
 ```
-[wolfssl osp root]\realm\realm-core\out\build\x64-Debug\src\realm\util
+[wolfssl osp root]\realm\realm-core[-username]\out\build\x64-Debug\src\realm\util
 ```
 
 ### Cannot find OpenSSL
@@ -128,4 +281,21 @@ openSSL disabled `0` and wolfSSL enabled `1` like this:
 #define REALM_HAVE_WOLFSSL 1
 ```
 
-###
+### CMake error Not a file: VerifyGlobs.cmake
+
+This file is typically not included in source control, but was found to be problematic when missing in this solution. Thus, there's a placeholder file.
+
+```
+1>Checking File Globs
+1>EXEC : CMake error : Not a file: C:/workspace/osp-gojimmypi/realm/VS2022/CMakeFiles/VerifyGlobs.cmake
+1>EXEC : CMake error : Error processing file: C:/workspace/osp-gojimmypi/realm/VS2022/CMakeFiles/VerifyGlobs.cmake
+```
+
+### Missing LibUV
+
+Open the cloned `realm-core` in Visual Studio and let cmake download and setup LibUV.
+
+```
+1> [CMake] -- Could NOT find LibUV (missing: LibUV_LIBRARY LibUV_INCLUDE_DIR) (found version "")
+1> [CMake] -- LibUV not found, building from source with FetchContent
+```

realm/VS2022/.gitignore

@@ -0,0 +1,18 @@
+# CMake backup files
+*.old
+*.bak
+
+# auto-downloaded & generated tar files
+*.tar.gz
+
+# temp files
+CTestCostData.txt
+
+# Log files
+LastTest.log
+LastTestsFailed.log
+
+# Build-time downloads and auto-generated files
+_CPack_Packages/**
+/install_manifest_runtime.txt
+/install_manifest_Unspecified.txt