First Build

To build Helios for the first time on Visual Studio 2019, you may need to work around some problems in how Visual Studio handles nuget packages. Specifically, the automatic inclusion of project file snippets from included NuGet packages.

For background, see https://sushihangover.github.io/nuget-and-msbuild-targets/

In practice, you may find that Visual Studio does not copy the native libraries to the build output on the first try, so nothing with native binaries will run correctly. This problem was previously observed with the Lua53.dll in various cases.

Please note that the Helios solution files include projects for the installers. You don't need to build the installers to run the product from the IDE or command line, but if you want to build them, then you need to install the optional support for projects of this type (see Building a Release). If you choose not to install this support into Visual Studio, then you will get error messages the first time you open the solution, because the installer projects will be of an unsupported type. You can just ignore these messages and keep the installer projects unloaded from then on.

Case 1: Using nuget.exe from the command line:

Note: you can get command line NuGet here: https://www.nuget.org/downloads

• Clone the repo
• Check out the branch you wish to build
• Before opening any solution file, just do nuget restore BuildMeFirst.sln and nuget restore Helios.sln in the root of your repo clone
• Build BuildMeFirst.sln (don't open Helios.sln yet!); this will download submodules and create files needed for Helios.sln
• Now open and build Helios.sln

Case 1b: If you have command line NuGet and MSBuild set up, including support for installer projects

(see Building a Release)

• Clone the repo
• Check out the branch you wish to build
• run nuget restore BuildMeFirst.sln
• run nuget restore Helios.sln
• run build test
  • this will do the prebuild, install submodules, generate templates, build Helios, and build an installer with the default version number
• you can now install to install the application or just build Helios.sln to start developing

Case 2: You don't use nuget from the command line normally:

The following workaround should be used:

• Clone the repo

• Check out the branch you wish to build

• Open BuildMeFirst.sln in Visual Studio

• Right-click the first item in the Solution Explorer (the Solution itself) and select "Restore NuGet Packages"

• (sometimes this doesn't work entirely, continue)

• Build the solution

  • this step "installs" the required nuget packages and make their automatic .props files and .targets files available for inclusion

• Close Visual Studio

• Open the same solution again

  • this time, Projects will actually include the automatically "included" files

• Clean solution

• Build solution

• Building the BuildMeFirst solution will have downloaded the git submodules because Visual Studio does not support them itself. It will also have generated fresh Simulator Viewport Templates that are needed for the Helios build. You can now open and build Helios.sln

Build Helios

The following build configurations are valid:

Target	Configuration	Purposes
x64	Debug	Testing product
x64	Release	Release of product or performance testing
x64	Development	Special build for testing with code that differs from product
AnyCPU	Debug	required by XAML Designer or Blend for User Code use
AnyCPU32	Debug	Testing 32-bit product
AnyCPU32	Release	Release of 32-bit product

See Build Configurations for more details.

The installers are built as part of the Solution, but not completely. The IDE will always build an installer for the default development version (currently 1.6.1000.0) and will not execute the post-build script to adjust the installer. The actual version number and other changes are only done by the command line build.

At the same time, the installers must not be permanently removed from the solution file, because they require access to the solution to find the other projects from which they take the output and content files.