From 47154e5f1b5efb0632385853dc761ef8dd92c239 Mon Sep 17 00:00:00 2001 From: Philip Howard Date: Thu, 15 Jul 2021 13:07:41 +0100 Subject: [PATCH 1/2] Revise Windows docs, prefer CMake --- docs/Windows-VisualStudio.md | 40 ++++++++++++++++++++++-------------- 1 file changed, 25 insertions(+), 15 deletions(-) diff --git a/docs/Windows-VisualStudio.md b/docs/Windows-VisualStudio.md index 5634cce71..4c1d6fcb8 100644 --- a/docs/Windows-VisualStudio.md +++ b/docs/Windows-VisualStudio.md @@ -1,27 +1,24 @@ # Visual Studio 2019 -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: @@ -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. @@ -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). @@ -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. @@ -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". @@ -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... { @@ -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}" } ] } //... ``` @@ -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. From b30678406b77a375ba013fbd812b59efead35cf4 Mon Sep 17 00:00:00 2001 From: Charlie Birks Date: Sat, 22 Jun 2024 20:25:52 +0100 Subject: [PATCH 2/2] docs: replace VS cross-build instructions with something that works in current VS --- docs/Windows-VisualStudio.md | 22 ++++++---------------- 1 file changed, 6 insertions(+), 16 deletions(-) diff --git a/docs/Windows-VisualStudio.md b/docs/Windows-VisualStudio.md index 4c1d6fcb8..d8c4fd2f4 100644 --- a/docs/Windows-VisualStudio.md +++ b/docs/Windows-VisualStudio.md @@ -76,19 +76,11 @@ There is also a skeleton game project created for you at https://github.com/32bl ### Building for 32Blit -1. Make sure the "Embedded and IoT development tools" component is installed from the `Linux development with C++` VS Workload. +1. Make sure the "Embedded and IoT development tools" component is installed from the `Linux development with C++` VS Workload and you have [an Arm toolchain](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads) installed. 2. Open the CMake Settings: `Project` > `CMake Settings`.. -3. Press "Add a new configuration..." and select "IoT-Release". - -4. Scroll down to "CMake toolchain file" and browse to `32blit.toolchain` - -5. (Optional) Change configuration name to something like "32Blit-Release" - -6. Save. - -7. Press "Edit JSON", scroll down to the new configuration and delete the contents of the `variables` array. The result should look like this: +3. Press "Edit JSON" and add a new entry to the "configurations" list like this (make sure to set the path to the toolchain file): ```jsonc // other configs... { @@ -104,19 +96,17 @@ There is also a skeleton game project created for you at https://github.com/32bl "variables": [], "intelliSenseMode": "linux-gcc-arm", "cmakeToolchain": "[path...]/32blit-sdk/32blit.toolchain", - "environments": [ { "PATH": "${env.PATH}" } ] + "environments": [ { "PATH": "${env.PATH}" } ] // this is a workaround for finding the toolchain } //... ``` -8. Select the new config and build! +4. Save. + +5. Select the new config and build! ## Troubleshooting ### 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.