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

Revise Windows docs, prefer CMake #691

Merged
merged 2 commits into from
Jun 22, 2024
Merged

Revise Windows docs, prefer CMake #691

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
47154e5
Revise Windows docs, prefer CMake
Gadgetoid Jul 15, 2021
b306784
docs: replace VS cross-build instructions with something that works i…
Daft-Freak Jun 22, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 25 additions & 15 deletions docs/Windows-VisualStudio.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,27 +1,24 @@
# Visual Studio 2019 <!-- omit in toc -->

You can use Visual Studio 2019 to examine the samples (compile them and run them in an SDL window) or to build your own apps for the 32blit API.
You can use Visual Studio 2019 to examine the examples (compile and run them on Windows using the SDL HAL) or to build your own apps for 32blit.

See [Building & Running On 32Blit](32blit.md) if you want to compile examples/projects to run on 32Blit.

- [Requirements](#requirements)
- [Option 1: Use the solution file](#option-1-use-the-solution-file)
- [Option 2: Use Visual Studio's built-in CMake support (Recommended)](#option-2-use-visual-studios-built-in-cmake-support-recommended)
- [Get started with your own game](#get-started-with-your-own-game)
- [Option 2: Use Visual Studio's built-in CMake support](#option-2-use-visual-studios-built-in-cmake-support)
- [Building your own game](#building-your-own-game)
- [Building for 32Blit](#building-for-32blit)
- [Troubleshooting](#troubleshooting)
- [Cannot open include file: 'SDL.h': No such file or directory](#cannot-open-include-file-sdlh-no-such-file-or-directory)
- [`cmd.exe` not recognised](#cmdexe-not-recognised)

## Requirements

You will need Visual Studio 2019 (preferably version 16.4).

Make sure you install C++ desktop development support.

You will also need to download SDL2 development libraries from the [SDL releases](https://github.com/libsdl-org/SDL/releases/latest). Here find the latest version of the VC development libraries (at the time of this writing SDL2-devel-2.24.0-VC.zip). Additionally, download SDL2_image from [here](https://github.com/libsdl-org/SDL_image/releases/latest) (SDL2_image-devel-2.6.1-VC.zip) and SDL2_net from [here](https://github.com/libsdl-org/SDL_net/releases/latest) (SDL2_net-devel-2.2.0-VC.zip).

Place these in the `vs\sdl\` folder. You will need to merge the include/lib directories. If you are using CMake/Open Folder, these are downloaded automatically.

Make sure you install "Desktop development with C++". If you plan to build for 32blit, you'll also need "Linux development with C++", making sure "C++ CMake tools for Linux" and "Embedded and IoT development tools" are selected in the "Optional" section.

There are two methods of building with Visual Studio:

Expand All @@ -33,7 +30,11 @@ The solutions and projects are made to use toolset version c142.

The solution file is located at `vs\32blit.sln`. It contains two static linked libraries, _32blit_ and _32blit-sdl_ and all the examples that will compile to .EXE.

## Option 2: Use Visual Studio's built-in CMake support
You will also need to download SDL2 development libraries from the [SDL releases](https://github.com/libsdl-org/SDL/releases/latest). Here find the latest version of the VC development libraries (at the time of this writing SDL2-devel-2.24.0-VC.zip). Additionally, download SDL2_image from [here](https://github.com/libsdl-org/SDL_image/releases/latest) (SDL2_image-devel-2.6.1-VC.zip) and SDL2_net from [here](https://github.com/libsdl-org/SDL_net/releases/latest) (SDL2_net-devel-2.2.0-VC.zip).

Place these in the `vs\sdl\` folder. You will need to merge the include/lib folders. If you are using CMake/Open Folder, these are downloaded automatically.

## Option 2: Use Visual Studio's built-in CMake support (Recommended)

This has the advantage of being closer to the build for the device.

Expand All @@ -45,6 +46,8 @@ This has the advantage of being closer to the build for the device.

To find the built files use `Project` > `CMake Cache` > `Open in Explorer`.

SDL libraries will be downloaded automatically by the CMake build system.

### Get started with your own game

There is also a skeleton game project created for you at https://github.com/32blit/32blit-boilerplate . This is an empty skeleton with some comments to get you started with your own game (if you do not want to start tweaking one of the examples).
Expand All @@ -55,13 +58,13 @@ There is also a skeleton game project created for you at https://github.com/32bl

2. `File` > `Open` > `Folder` and open the folder containing your game.

3. `Project` > `CMake Settings`.
3. Open the CMake Settings: `Project` > `CMake Settings`.

4. Scroll down to the CMake variables and wait for the list to load.

5. Press the "Browse..." button next to `32BLIT_DIR`.

6. Browse to the folder containing the 32blit repo.
6. Browse to the folder containing the 32blit SDK.

7. To add a release configuration, press "Add a new configuration..." (the plus button under "Configurations"), select "x64-Release" and repeat steps 4-6 on the new configuration.

Expand All @@ -75,7 +78,7 @@ There is also a skeleton game project created for you at https://github.com/32bl

1. Make sure the "Embedded and IoT development tools" component is installed from the `Linux development with C++` VS Workload.

2. Open the CMake Settings (see above).
2. Open the CMake Settings: `Project` > `CMake Settings`..

3. Press "Add a new configuration..." and select "IoT-Release".

Expand All @@ -85,7 +88,7 @@ There is also a skeleton game project created for you at https://github.com/32bl

6. Save.

7. Press "Edit JSON", scroll down to the new conficuration and delete the contents of the `variables` array. The result should look like this:
7. Press "Edit JSON", scroll down to the new configuration and delete the contents of the `variables` array. The result should look like this:
```jsonc
// other configs...
{
Expand All @@ -100,7 +103,8 @@ There is also a skeleton game project created for you at https://github.com/32bl
"inheritEnvironments": [ "gcc-arm" ],
"variables": [],
"intelliSenseMode": "linux-gcc-arm",
"cmakeToolchain": "[path...]/32blit-sdk/32blit.toolchain"
"cmakeToolchain": "[path...]/32blit-sdk/32blit.toolchain",
"environments": [ { "PATH": "${env.PATH}" } ]
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While that does fix the build, it usually breaks configuring as it resets the PATH set by the "gcc-arm" environment containing the cross tools... (Works after configuring as all the paths are cached)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if it can do something like append to the path rather than completely trounce it. I assume you've probably bashed your head against this quite a bit! 😬

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That said, I can't seem to get it to break configuration. Even after deleting the cache.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah I kept trying to workaround it in 32blit setup... and eventually got annoyed enough to remember my MS account and report it.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That said, I can't seem to get it to break configuration. Even after deleting the cache.

Possibly finding some other installed toolchain instead of the VS supplied one? It definitely doesn't find the one shipped with VS with that override.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oooh that's something to check. Might be prudent to remove the ARM GCC toolchain since that's in my path.

I strongly suspect there wont be a fix for this imminently and we'd have to bless the command-line procedure for actual on-device builds. Which isn't so bad.

Or, I guess, if it's gonna detect ARM GCC and work... that's also fine?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hah, maybe it'll work in VS 2022, who knows... There's always VS Code (and probably most other editors) to make the "command-line" builds less... command-line.

Guess the problem with an "external" toolchain is it might stop working, as finding that instead of the VS one probably isn't supposed to work. Might mess up intellisense or something 🤷

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You're right- it finds the ARM GCC toolchain I installed. Makes sense!

This... sort-of... fix does the trick in both cases:

"environments": [ { "PATH": "${env.ProgramFiles(x86)}/Microsoft Visual Studio/2019/Community/Linux/gcc_arm/bin/;${env.PATH}" } ]

It's ugly, and I'd feel a lot happier if I could find a way to get the full path to the currently running Visual Studio but there doesn't seem to be a way. Also not sure if I'm subtly breaking something by supplying the wrong executable, my install isn't exactly clean!

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In VS2022 it seems that the "IoT" configs are gone, so the only way to get this to work is to install the Arm toolchain and manually add a config similar to the one above. (Including the PATH hack...)

Anyway, I was in the area so I've rebased this.

}
//...
```
Expand All @@ -109,4 +113,10 @@ There is also a skeleton game project created for you at https://github.com/32bl

## Troubleshooting

If you see errors such as `Cannot open include file: 'SDL.h': No such file or directory` and `cannot open file 'SDL2.lib'` you've probably extracted the SDL development libraries wrong. Inside your sdl folder you should have the folders docs, include and lib not SDL2-2.0.10.
### Cannot open include file: 'SDL.h': No such file or directory

If you see errors such as `Cannot open include file: 'SDL.h': No such file or directory` and `cannot open file 'SDL2.lib'` you've probably extracted the SDL development libraries into "SDL2-2.24.0" rather than extracting the individual folders inside. Inside your "sdl" folder you should have the folders "docs", "include" and "lib" not "SDL2-2.24.0".

### `cmd.exe` not recognised

Building for 32blit can fail with `'cmd.exe' is not recognized as an internal or external command, operable program or batch file`. This is a bug in Visual Studio (reported https://developercommunity.visualstudio.com/t/CMake-with-the-IoT-toolchain-fails-wit/1429737) which can be fixed by adding the `"environments": [ { "PATH": "${env.PATH}" } ]` line to the CMake config.
Loading