Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Introduce realm-core Visual Studio 2022 projects #229

Merged
merged 1 commit into from
Jan 23, 2025
Merged

Introduce realm-core Visual Studio 2022 projects #229

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
65 changes: 64 additions & 1 deletion .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

1 change: 1 addition & 0 deletions realm/CMakeLists.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
message(STATUS "wolfSSL OSP Realm CMake")
184 changes: 177 additions & 7 deletions realm/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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

Expand All @@ -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
Expand All @@ -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
```
18 changes: 18 additions & 0 deletions realm/VS2022/.gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Loading