From 690b811a02fcf7ec46905b08eadf46788fba7350 Mon Sep 17 00:00:00 2001 From: Dustin Long Date: Fri, 7 Apr 2023 14:18:51 -0400 Subject: [PATCH] Improve Windows support and update the docs installation guide On Windows, run a postinstall script that will copy the SDL2.dll dynamic library from the devel source to the build directory. This is required so that running the native addon will successfully find the dynamic library. Update docs to reflect that SDL is now hosted on github, and to clarify the steps to install the native addon. --- README.md | 14 +++++++++++--- package.json | 3 ++- tools/locate_sdl.js | 18 +++++++++++++----- tools/windows_copy_dll.js | 19 +++++++++++++++++++ 4 files changed, 45 insertions(+), 9 deletions(-) create mode 100644 tools/windows_copy_dll.js diff --git a/README.md b/README.md index afd5172..2e4e46a 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,7 @@ ra.show(); ![](asset/example.png) -# Building +# Installing You can use raster.js either in the browser using canvas, or on the command-line using node.js (graphics will appear in a new SDL window). @@ -50,9 +50,17 @@ npm run build which outputs `dist/raster.min.js` +You can also create a development build (less efficient, but better for debugging) by running: + +``` +npm run dev +``` + ### Node.js -Building requires SDL2 development libraries. See below for platform specific details. Once you have them properly setup, run +Installing raster.js for use with node.js requires setting up an environment that can build native add-ons. This means you need to install Python and a C++ compiler, see [the node-gyp instructions for your operating system](https://github.com/nodejs/node-gyp#installation). + +Using SDL requires the installing the SDL2 development libraries. See below for platform specific details. Once you have them properly setup, run ``` npm install raster @@ -64,7 +72,7 @@ On macos, run `brew install sdl2` to get SDL2. ### SDL2, Windows -For Windows, only [msys2](https://www.msys2.org/) is currently supported. Go to [this page](https://www.libsdl.org/download-2.0.php) and get `SDL2-devel-2.0.16-mingw.tar.gz`. Extract the `SDL2-2.0.16` folder and place it within the directory `c:/SDL/`, so that it ends up at `c:/SDL/SDL2-2.0.16/`. If you use to use a different location instead of `c:/SDL/`, assign that location to the environment variable `SDL_PATH`. +For Windows, it is recommended to use [msys2](https://www.msys2.org/), but Powershell and WSL will probably work too. Grab the latest [SDL release](https://github.com/libsdl-org/SDL/releases) and get `SDL2-devel--mingw.zip`. Extract this zip to get the `SDL2-` folder and place it within the directory `c:/SDL/`, so that it ends up at `c:/SDL/SDL2-/`. If you use to use a different location instead of `c:/SDL/`, assign that location to the environment variable `SDL_PATH`. # Getting started diff --git a/package.json b/package.json index 56421dd..e83b925 100644 --- a/package.json +++ b/package.json @@ -15,7 +15,8 @@ "sdl-test": "mocha test/sdl/", "web-test": "karma start --single-run --browsers FirefoxHeadless karma.conf.js --", "build": "webpack", - "dev": "webpack --config webpack.dev.js" + "dev": "webpack --config webpack.dev.js", + "postinstall": "node tools/windows_copy_dll.js" }, "dependencies": { "argparse": "^2.0.1", diff --git a/tools/locate_sdl.js b/tools/locate_sdl.js index 840a88b..1291c7b 100644 --- a/tools/locate_sdl.js +++ b/tools/locate_sdl.js @@ -1,7 +1,7 @@ var fs = require('fs'); var path = require('path'); -var SYSTEM_PATHS = [ +var LIB_PATHS = [ '/lib', '/usr/lib', '/usr/lib64', @@ -15,8 +15,8 @@ var SYSTEM_PATHS = [ ]; function locateSDL(mode) { - if (mode != 'include' && mode != 'lib' && mode != 'symbol') { - throw new Error(`illegal mode "${mode}", use "include", "lib", or "symbol"`); + if (mode != 'include' && mode != 'lib' && mode != 'dll' && mode != 'symbol') { + throw new Error(`illegal mode "${mode}", use "include", "lib", 'dll', or "symbol"`); } if (process.platform == 'darwin') { return locateSDLMacos(mode); @@ -29,13 +29,16 @@ function locateSDL(mode) { function locateSDLMacos(mode) { let basename = ''; - for (let i = 0; i < SYSTEM_PATHS.length; i++) { - let root = SYSTEM_PATHS[i]; + for (let i = 0; i < LIB_PATHS.length; i++) { + let root = LIB_PATHS[i]; if (mode == 'include') { root = root.replace('/lib', '/include'); basename = 'SDL2'; } else if (mode == 'lib') { basename = 'libSDL2.dylib'; + } else if (mode == 'dll') { + root = root.replace('/lib', '/bin'); + basename = 'SDL2.dll'; } else if (mode == 'symbol') { basename = 'libSDL2.dylib'; } @@ -60,6 +63,9 @@ function locateSDLWindows(mode) { } else if (mode == 'lib') { let dir = getWindowsSDLDir('c:/SDL/'); return path.posix.join(dir, "/lib/libSDL2.dll.a"); + } else if (mode == 'dll') { + let dir = getWindowsSDLDir('c:/SDL/'); + return path.posix.join(dir, "/bin/SDL2.dll"); } else if (mode == 'symbol') { let dir = getWindowsSDLDir('c:/SDL/'); if (fs.existsSync(path.posix.join(dir, "/lib/libSDL2.dll.a"))) { @@ -97,6 +103,8 @@ function findFolderInDir(dir, regex) { return ''; } +module.exports.locateSDL = locateSDL; + if (require.main === module) { var mode = process.argv[2]; process.stdout.write(locateSDL(mode)); diff --git a/tools/windows_copy_dll.js b/tools/windows_copy_dll.js new file mode 100644 index 0000000..d302b75 --- /dev/null +++ b/tools/windows_copy_dll.js @@ -0,0 +1,19 @@ +const locateSDL = require('./locate_sdl.js'); +const fs = require('fs'); +const path = require('path'); + + +function copyDynamicLibToBuild(sdlpath) { + let basename = path.basename(sdlpath); + let dest = path.join(__dirname, '../build/Release/', basename); + console.log(`post-install script for Windows only: copying dynamic library from "${sdlpath}" to "${dest}"`); + fs.copyFileSync(sdlpath, dest); +} + + +if (require.main === module) { + if (process.platform != 'win32') { + return; + } + copyDynamicLibToBuild(locateSDL.locateSDL('dll')); +}