Debugging WASM gauges How-To

[DragonflightDesign]

The instructions for debugging WASM gauges in the SDK is... somewhat lacking in completeness. They imply (actually, pretty much state) that once you have attached the debugger to MSFS you do not need to disconnect it for that session. This is not so. If you don't disconnect it, you will never get an updated .pdb file copied to the project folder. The result of that will be that the debugger cannot connect to the updated WASM module.

From SU12 onwards you must also do the following:

1. Start Steam
2. Find MSFS in your library and right-click | select Properties
3. Add the following to the Launch Options box:

-FastLaunch -AllowDebugger

The first bypasses the Asobo screens and is optional, but you MUST have -AllowDebugger. If you do not, then any attempt to attach a debugger to MSFS will crash the sim. No, it's not in the SDK but it is in the SU12 update notes.

From the top:

1. (Optional) Open Windows Explorer to C:\Users\<username>\AppData\Roaming\Microsoft Flight Simulator\packages\
2. Build your WASM module and copy it to the (...)\PackageSources\SimObjects\Airplanes\<myAircraft>\panel\ folder
3. Start MSFS
4. Attach the debugger any time after the sim starts displaying the splash screens (from the Visual Studio menu, Debug | Attach to Process | select FlightSimulator.exe)
5. Once you arrive at the main menu, build your project from the Devmode menu (File | etc.)
6. Load/create a scenario with the new aircraft in it. As MSFS compiles the WASM module to a debug .dll, if you have done step (1) then you will see a new folder appear with the name of your aircraft. In that folder you will see a bunch of files all with the same cryptic name but with different suffixes: .dll, .cache, .obj, .lib, .pdb and .natvis. There is also a sub-folder called 'work' but I've never seen anything in that yet
7. Start the flight. If all has gone well, the breakpoints in the debugger should now attach to the .dll and .pdb files.

To update the WASM module:

8. Detach the debugger from MSFS (Visual Studio Debug | Stop Debugging)
9. Build your WASM module and copy it to the (...)\PackageSources\SimObjects\Airplanes\<myAircraft>\panel\ folder
10 (Optional) Manually delete the files from the C:\Users\<username>\AppData\Roaming\Microsoft Flight Simulator\packages\<myProject> folder. This at least ensures that you know the compiled files will be up to date
11. Build your project from the Devmode menu (File | (...))
12. Re-attach the debugger
13. Start the scenario.

If you're not afraid of experimental stuff, see also this topic on the MSFS dev forum:-

EDITED TO REMOVE DEAD LINK.

My guess is this will become standard at some point.

-Dai

 

[DragonflightDesign]

> From SU12 onwards you must also do the following:

If anyone can give me the Microsoft Store equivalent to add to the main post I'd be very grateful.

 

[WarpD]

Not sure how you'd pull that off... the shortcut (.lnk file) doesn't allow for any modifications... at least on my system it doesn't So, I'm not certain you can make these mods to the non-Steam installation. Hopefully someone will waltz in here and prove me wrong.

 

[DragonflightDesign]

Must be some way of doing it, Ed. This from the SU12 update notes:

WASM​

IMPORTANT: Debuggers (ie: the Visual Studio debugger) can no longer be attached to the executable by default. If you do, the simulation will crash. In order to be able to debug you (sic) WASM module, you have to pass the argument "-AllowDebugger" to the exe

 

[WarpD]

Yeah.. the default install of the sim doesn't support custom command lines. So, I suspect one will have to create their own shortcut to start the sim. Like I said... hopefully someone can waltz in to prove me wrong.

 

[=rk=]

C:\MSFS SDK\Tools\bin\fsdevmodelauncher.exe?

 

[Ronald]

The instructions for debugging WASM gauges in the SDK is... somewhat lacking in completeness.

Since when in Microsoft / FlightSimulator(tm) history has any MSFS SDK been fully transparent and fully documented ???
Reading this SU12 release update feels like Asobo is doing their very best to totally shutdown any (freeware) access for all non "Microsoft partnered" developers in the long run.
Just sharing an observation here

 

[WarpD]

C:\MSFS SDK\Tools\bin\fsdevmodelauncher.exe?

Sorry, but I don't develop for FS2020... and didn't bother going through every single folder of it's SDK to see what was there... so, that's on me... BUT...

The source code for the app is in the SDK and it does NOT have the -AllowDebugger argument, but DOES have the -FastLaunch argument. Of course, I haven't updated my SDK yet this month... so, maybe it's changed?

 

[=rk=]

Unlikely, but within the same directory are several iterations of fsdevmodelauncher.exe.

 

[WarpD]

In my "MSFS SDK/Tools/Bin" I see:

• bglcomp.xsd
• bglcomp_gltfv1_1.xsd
• BglExplorer.exe
• fsdevmodelauncher.exe
• fspackagetool.exe
• fspackagetool_overrideExePath.txt

I don't see several iterations. Nor do I understand why there would be since there would be no way to tell which one did or didn't do what.

 

[DragonflightDesign]

Rik: -AllowDebugger is a parameter for FlightSimulator.exe. It's my opinion (and Ed's, as it happens) that if you're using the MS Store version you need to create a shortcut to FlightSimulator.exe and add -FastLaunch -AllowDebugger to the command line. As I don't have the MS Store version, I cannot present that as fact in the initial post.

 

[=rk=]

Rik: -AllowDebugger is a parameter for FlightSimulator.exe. It's my opinion (and Ed's, as it happens) that if you're using the MS Store version you need to create a shortcut to FlightSimulator.exe and add -FastLaunch -AllowDebugger to the command line. As I don't have the MS Store version, I cannot present that as fact in the initial post.

I do have MS Store version, I have no experience with gauge development but I read along because I intend to learn.

Nor do I understand why there would be since there would be no way to tell which one did or didn't do what.

I will observe that the extra versions of fsdevmodelauncher my SDK contains, are modified with the same letter that spells "debugger" and if there are any tests my simple brain can run to settle any uncertainties, I'll do so.

 

[WarpD]

That date on the fsdevmodelauncher_d.exe is from 2021.... very old. I don't have an SDK that old. I just installed the latest SDK and that launcher doesn't exist in my install. So... ya certain you didn't compile a version from an older source?

 

[=rk=]

My SDK is continually updated with successive builds and items are on occasion removed. The fact that these have not been removed implies oversight, as equally as it attests to their validity, which I myself cannot. I doubt there is any harm in sharing them, or testing them for you if you could tell me how.

 

[ehillrti]

Thank you @DragonflightDesign for the excellent guide to getting WASM debugging up and running! The hint about -AllowDebugger was especially useful.

Your guide helped me get much farther than I had previously but I still can't seem to get breakpoints to work. In my C:\Users\<username>\AppData\Roaming\Microsoft Flight Simulator\Packages\<myAircraft>\ folder I'm seeing the .cache, .dll, .lib, and .obj files get populated as MSFS compiles the WASM module after I launch a flight, BUT I don't see a .pdb or .natvis file in that folder. I suspect those missing files are why my breakpoints are disabled and have a tooltip saying "The breakpoint will not currently be hit. No symbols have been loaded for this document." I am of course building my WASM module in Debug mode in VS2019. Any suggestions as to what I might be missing or doing wrong?

FYI, my WASM gauge project is just a slight modification to the MouseAircraft sample project and I haven't changed any of the VS project settings.

Thanks for any help!

 

[DragonflightDesign]

Check your setup as described in the SDK. If I were to make a complete guess-in-the-dark, if you check under Project | Properties | Linker | Debugging you may have debugging set to No, even though C/C++ | General | Debug Information Format says Program Database. Under the Linker it should say Generate Debug Information.

 

[ehillrti]

Thanks for the suggestion, but that was one of the first things I checked. I'm new to WASM builds so I was a little surprised that there was not a pdb file generated in the \Debug folder that VS2019 outputs to. Is that normal? Is the debug information embedded in the .wasm file? The post-build step is only copying the .wasm file into the \<myAircraft>\panel\ folder. Are there other files that need to be copied for debugging?

Project Properties:

Results of the compile:

 

[DragonflightDesign]

Ahhh.... you don't get a .pdb file until MSFS compiles the .wasm module into a .dll. So no, the breakpoints won't be hit until the aircraft is loaded. You should see it appear in here:

C:\Users\<username>\AppData\Roaming\Microsoft Flight Simulator\packages\<your aircraft name>

 

[ehillrti]

Yes, I saw 4 files appear in that folder shortly after I started a flight with this test aircraft (.cache, .dll, .lib, .obj) but no .pdb or .natvis. I didn't even try to set a breakpoint until after the flight had started. VS2019 attached and later detached to/from FlightSimulator.exe just fine, just no breakpoints. Is there a flag or something in the MSFS project build process that tells MSFS to generate debug output (.pdb/.natvis files) along with those other 4 files?

 

[ehillrti]

PROBLEM SOLVED! Truly newby mistake that I hate to admit but hopefully it will help someone else that is just getting started trying to debug WASM gauges.

Turns out, my WASM Build type was DEBUG like I wanted but the DLL build type was still RELEASE. I discovered this by looking in the Wasm Debug window (under the Debug menu):

The way to fix this is to turn on the "Fast WASM Compilation" switch under the Options menu:

After turning on that switch then backing out to the Main Menu, reloading the aircraft/gauge project, cleaning, then rebuilding the project and starting a new flight, the Wasm Debug window showed that the DLL was being built in DEBUG mode:

The runtime build folder now contains all six file types including .pdb and .natvis. Most importantly, when I attach VS2019 to FlightSimulator.exe, I can set breakpoints that stop when they're supposed to and nothing crashes!

Of course, I wouldn't have gotten this far without the post from @DragonflightDesign at the top of this thread so thank again @DragonflightDesign !!!