Guide: Orbiter development in Visual Studio 2019

[DarkWanderer]

Hi,

Seeing a lot of questions pertaining to how to develop Orbiter using Visual Studio 2019, I've decided to share the setup I use

Steps:

1.Install latest version of Visual Studio 2019​

Required components:

• "Desktop Development with C++" package
• "MFC for latest build tools" component under "Individual Components"

Optional:

• Install "Git for Windows" from here to skip next step

2.Install Git for Windows​

Self-explanatory. Link to official download: https://git-scm.com/download/win

3.Clone Orbiter repository​

cd %userprofile%
git clone https://github.com/orbitersim/orbiter.git

4.Open Orbiter directory in Visual Studio​

Make sure to use "Open a local folder" and not "Open a project or solution"

5.Set up "CMake Settings"​

By default, Visual Studio will try to build Orbiter in x64-Debug configuration.

• to create other configurations, go to "CMake Settings for Orbiter", or use the template from step 6
• it is recommended to point ORBITER_PLANET_TEXTURE_INSTALL_DIR variable to Textures directory of an existing Orbiter 2016 installation

6.Optional: Paste CMakeSettings.json​

​

​

Navigate to "Edit JSON file" in CMake Settings, then paste the contents of attached CMakeSettings.json file there. Replace G:\\Games\\Orbiter\\Textures with path to your Orbiter installation (don't forget the double slashes). After you do so, you'll see an expanded set of configurations to choose from:

7.Configure​

This step may happen automatically depending on your VS settings (you'll see some cmake logs in "Output" window)

8.Build​

9.Set up launch settings for Orbiter_NG version​

Select "Orbiter.exe (Modules\\Server\\Orbiter.exe)" in launch target dropdown. Go to "Debug"=>"Debug and Launch settings for Orbiter_server".

Paste below JSON into opened launch.vs.json file:

{
  "version": "0.2.1",
  "defaults": {},
  "configurations": [
    {
      "currentDir": "out/build/${cmake.name}",
      "type": "default",
      "project": "CMakeLists.txt",
      "projectTarget": "Orbiter.exe (Modules\\Server\\Orbiter.exe)",
      "name": "Orbiter.exe (Modules\\Server\\Orbiter.exe)"
    }
  ]
}

This will set up the working directory correctly, so Orbiter.exe can find all the modules and scenarios despite being placed in a subdirectory

Congratulations! You have a working setup to build Orbiter

 

[supersonic71]

I just created an account to ask "what are the required components for Visual Studio" and then right in time I saw this post!
Many thanks.

 

[mxk]

Very good guide it is a very useful.

 

[DaveS]

Just one question: Where does the build process dump all the built binaries? I can't seem to find them.

Edit: Never mind, found the stuff in the "out\x64-release" subfolder. What do I need to change for it to dump the stuff in an easier to find folder? Also how do we keep the installation up-to-date?

 

[DarkWanderer]

You can adjust build and "install" directory to your liking in your CMakeSettings.

Not entirely clear what do you mean by "keeping installation up to date" - you mean updating the repository? This can be done either by "git pull" command, or by using Git Changes window in Visual Studio - it has a "pull" command as well

 

[DaveS]

Now I guess the questions if this guide will only cover obtaining the main Orbiter Git repository and building it or if it will cover obtaining the external repositories of D3D9Client and XRSound?

 

[DarkWanderer]

XRSound is part of Orbiter repository already - you need to download irrKlang SDK for it separately because of licensing issues (@dbeachy1 can probably comment on it more)

D3D9Client will be integrated soon™ - there's a WIP branch to merge it

 

[dbeachy1]

See https://github.com/orbitersim/orbiter/tree/main/Sound/XRSound for details about how to configure and build XRSound via its VS 2019 solution file. XRSound is also built along with the Orbiter core if you enable that and configure irrKlang paths in Orbiter's CMake settings.

And yes, @DarkWanderer is correct that the irrKlang SDK must be downloaded from the irrKlang Web site in order to comply with its license; users are not permitted to host the irrKlang SDK files in other repositories.

 

[jarmonik]

Still haven't had much luck to get this to work. But it did finish building it at-least once.

• It seems to be building "x64-Debug" regardless of what ever is selected.
• Output seems to go [CMAKE_SOURCE_DIR]/out/build/x64-Debug/ and [CMAKE_SOURCE_DIR]/out/install/orbiter/ regardless of build root.
• After a few build attempts it just hangs and refuses to build anything. Clicking "Re-build All" immediately displays "Build All Failed !". Deleting "out" and ".vs" dirs doesn't release lockup.
• At some point clicking "Clear All" or something else wiped out my whole Orbiter installation pointed by "root dir" and left some unknown files in place. This is not good.

 

[jarmonik]

Not entirely clear what do you mean by "keeping installation up to date" - you mean updating the repository?

I believe this means keeping your local Orbiter Installation updated with latest binaries compiled from the repository while preserving high-res textures, add-ons and add-on development work in place in that directory like C:/Orbiter/. The last thing user want's is to get it wiped out empty.

 

[DarkWanderer]

Sorry to hear that - did you have build dir in your Orbiter directory, however? That has potential for failure regardless of whether you use Visual Studio or command line.

If you need a "merged" install, at the very least it should be "install" dir which is pointing to an active installation, and ideally - a separate base copy of Orbiter 2016 which you then "install" into

 

[jarmonik]

Sorry to hear that - did you have build dir in your Orbiter directory, however? That has potential for failure regardless of whether you use Visual Studio or command line.
If you need a "merged" install, at the very least it should be "install" dir which is pointing to an active installation, and ideally - a separate base copy of Orbiter 2016 which you then "install" into

Yes, the "Build Root" was pointing into my Orbiter Installation. So, it would look like that "CMAKE_BINARY_DIR" is not the place where-to build the binaries, but it's just a cache directory for cmake and build related files. So, the "CMAKE_INSTALL_PREFIX" would be the final destination for files. But it looks like it want's the add "/Orbiter/" into the path specified. In my case the folder name is "OrbiterWin32" so it can't install the files in there. Developers usually have multiple installations of Orbiter, therefore a fixed name could be a problem.

 

[DarkWanderer]

Yes, the "Build Root" was pointing into my Orbiter Installation. So, it would look like that "CMAKE_BINARY_DIR" is not the place where-to build the binaries, but it's just a cache directory for cmake and build related files. So, the "CMAKE_INSTALL_PREFIX" would be the final destination for files. But it looks like it want's the add "/Orbiter/" into the path specified. In my case the folder name is "OrbiterWin32" so it can't install the files in there. Developers usually have multiple installations of Orbiter, therefore a fixed name could be a problem.

Yes, that is correct. In make/CMake terms the "build" directory is a temporary scratchpad and the "install" is the one with final product (although personally I would still install into separate dir to be in the safe side). The target model withCMake is that you have source dirs in safety and the build/install happens in separate safe location

"Orbiter" directory being added to the end of installation path is something which is set in original CMakeLists by @martins - it can probably be discussed to remove it

 

[jarmonik]

I have detected couple of problems. The first attempt to build or install orbiter usually fails. The second attempt to build or install usually is success even if no modifications are made. Could this be dependency issues ?

The second problem is that install overwrites Orbiter.cfg / D3D9Client.cfg with default setting. When doing development and testing it would be necessary maintain the existing configuration in install destination. Usually a development install (update) would only require updating binaries and shaders. Not sure how to implement that properly.

 

[DarkWanderer]

I have detected couple of problems. The first attempt to build or install orbiter usually fails. The second attempt to build or install usually is success even if no modifications are made. Could this be dependency issues ?

The second problem is that install overwrites Orbiter.cfg / D3D9Client.cfg with default setting. When doing development and testing it would be necessary maintain the existing configuration in install destination. Usually a development install (update) would only require updating binaries and shaders. Not sure how to implement that properly.

I don't experience that, what is the error message?

For .cfg files - I guess the correct way to solve it would be to have a customized "install" command for CMake which mimics "copy if newer" Visual Studio behavior. I know it is possible in theory, will need to dedicate some time to implement

 

[s0ulinvictus]

I've got a lot to learn about C++, so much that I'm not even sure what questions to ask..

So, I've managed to compile and run Orbiter from the repo using VS2019 CE. What I'm wanting to do is learn C++, in the same way I've learned a lot about Lua/SASL in XPlane11 - make changes to existing code, and test. I picked an add-on MFD, Orrery, to begin experimenting with. There are also a few others that come with source, and perhaps there is in fact a better one for what I'm trying to do.

Just to be clear, nothing I do will ever be uploaded anywhere unless I have the original authors express consent. This is solely for me to learn.

That being said, I haven't yet been able compile any add-ons from source with or without changes, because basically I don't know what I'm doing when it comes to setting up CMake, VS projects, solutions, etc. As I said, I did manage to compile the repo, after tracking down some errors, and it does work, but if there were some general guidelines, perhaps in laymans terms, about how to use the Orbiter SDK, beyond what is in the extensive documentation included, specifically as it concerns how to know what you will need in order to build an MFD, the CMakelist, and all of the "tooling" I guess. And also more generally as well, how to know what you need when starting a C++ project, and navigating SDK's. And honestly it really seems like all the information I'm asking for is in the SDK documentation, I just don't quite know the lingo yet.

Anyway, any help is much appreciated.

 

[JDat]

To my understanding there are two different things:

• Open source Orbiter, what you already successfully compiled
• 3rd party addons, who are separate projects/solutions

Because there are some nifty things to get 3rd party addon compiled, I recommend you to start learn by recomilling Rcontrol and MFDtemplate addons from Open source Orbiter. Some time ago I successfully compiled them together with orbiter.

I successfully added to Rcontrol additional buttons and code for controlling vessel aerosurfaces. But Rcontrol is more like dialog addon example
From now for me MFD addon coding also is more or less clear, but not tried yet to do anything useful. For example, try to write your own Orbit MFD using original Orbiter code source code. There is reason why this can be useful in nearest future.
You can also try to undestand and play with Deltaglider source code. More complex, but interesting to understand how to implement subsystem (electrical, life support etc) simulation.

Keep going and you will get success!

 

[supersonic71]

Hey I think I managed to build it! I was getting some error but after reloading the project it worked.
Whats the difference between debug and release?
I built using release. When I tried to run a scenario from Orbiter.exe, it said " Running in server mode (no graphics client attached). ". How do I run it with the default dx7 (or if possible, the latest d3d9) client?
Edit : previously I built x64-release and I had the issue (no graphics client attached). After building with x86-release, it works as intended (dx7 client opens).

 

[DaveS]

I am also interested in getting set up with a development build of D3D9Client, more specifically this branch: https://github.com/jarmonik/orbiter/tree/atmo-remake

 

[n72.75]

See https://github.com/orbitersim/orbiter/tree/main/Sound/XRSound for details about how to configure and build XRSound via its VS 2019 solution file. XRSound is also built along with the Orbiter core if you enable that and configure irrKlang paths in Orbiter's CMake settings.

And yes, @DarkWanderer is correct that the irrKlang SDK must be downloaded from the irrKlang Web site in order to comply with its license; users are not permitted to host the irrKlang SDK files in other repositories.

Is doing this with environment variables the best way?