Merge pull request #14514 from lujun9972/add-MjAxODEyMjAgRCBpbiB0aGUgQnJvd3NlciB3aXRoIEVtc2NyaXB0ZW4sIExEQyBhbmQgYmluZGJjLXNkbCAodHJhbnNsYXRpb24pLm1kCg==

自动选题: 20181220 D in the Browser with Emscripten, LDC and bindbc-sdl (translation)
2025-01-16 22:42:21 +08:00 · 2019-07-09 17:46:28 +08:00 · 2019-07-09 17:46:28 +08:00 · 45b04f06b8
commit 45b04f06b8
parent c7c59bb52f e36bf9af88
1 changed files with 276 additions and 0 deletions
--- a/sources/talk/20181220
+++ b/sources/talk/20181220
@ -0,0 +1,276 @@
+[#]: collector: (lujun9972)
+[#]: translator: ( )
+[#]: reviewer: ( )
+[#]: publisher: ( )
+[#]: url: ( )
+[#]: subject: (D in the Browser with Emscripten, LDC and bindbc-sdl (translation))
+[#]: via: (https://theartofmachinery.com/2018/12/20/emscripten_d.html)
+[#]: author: (Simon Arneaud https://theartofmachinery.com)
+
+D in the Browser with Emscripten, LDC and bindbc-sdl (translation)
+======
+
+Here’s a tutorial about using Emscripten to run D code in a normal web browser. It’s uses a different approach from the [Dscripten game demo][1] and the [dscripten-tools][2] toolchain that’s based on it.
+
+  * Instead of porting the D runtime, it uses a lightweight, runtimeless `-betterC` build.
+  * It uses Docker to manage the Emscripten installation.
+
+
+
+LDC has recently gained support for [compiling directly to WebAssembly][3], but (unlike the Emscripten approach) that doesn’t automatically get you libraries.
+
+You can find [the complete working code on Github][4]. `./run.sh` starts a shell in a Docker image that contains the development environment. `dub build --build=release` generates the HTML and JavaScript assets and puts them into the `dist/` directory.
+
+[This tutorial is translated from a Japanese post by outlandkarasu][5], who deserves all the credit for figuring this stuff out.
+
+### Background
+
+#### What’s Emscripten?
+
+[Emscripten][6] is a compiler toolchain for asm.js and WebAssembly that comes with ported versions of the libc and SDL2 C libraries. It can compile regular Linux-based applications in languages like C to code that can run in a browser.
+
+### How do you use Emscripten with D?
+
+Emscripten is a toolchain designed for C/C++, but the C/C++ part is just a frontend. The toolchain actually compiles LLVM intermediate representation (IR). You can generate LLVM IR bitcode from D using [LDC][7], so it should be possible to feed that through Emscripten and run D in a browser, just like C/C++.
+
+#### Gotchas using Emscripten
+
+Ideally that’s all it would take, but there are some things that require special attention (or trial and error).
+
+  1. D runtime library features like GC and Phobos can’t be used without an Emscripten port.
+  2. It’s not enough to just produce LLVM IR. The code needs to meet Emscripten’s requirements.
+    * It needs to use ported libraries.
+    * Pointer sizes and data structure binary layouts need to match.
+  3. Emscripten bugs need to be worked around.
+    * Debug information is particularly problematic.
+
+
+
+### Implementation
+
+#### Plan of attack
+
+Here’s the plan for making D+Emscripten development work:
+
+  1. Use `-betterC` and the `@nogc` and `nothrow` attributes to avoid D runtime features.
+  2. Use SDL2 functions directly by statically compiling with [`bindbc-sdl`][8].
+  3. Keep on trying.
+
+
+
+#### Environment setup
+
+Emscripten is based on LLVM, clang and various other libraries, and is hard to set up, so I decided to [do the job with Docker][9]. I wrote a Dockerfile that would also add LDC and other tools at `docker build` time:
+
+```
+FROM trzeci/emscripten-slim:sdk-tag-1.38.21-64bit
+
+# Install D and tools, and enable them in the shell by adding them to .bashrc
+RUN apt-get -y update && \
+    apt-get -y install vim sudo curl && \
+    sudo -u emscripten /bin/sh -c "curl -fsS https://dlang.org/install.sh | bash -s ldc-1.12.0" && \
+    (echo 'source $(~/dlang/install.sh ldc -a)' >> /home/emscripten/.bashrc)
+
+# dub settings (explained later)
+ADD settings.json /var/lib/dub/settings.json
+```
+
+Docker makes these big toolchains pretty easy :)
+
+#### Coding
+
+Here’s a basic demo that displays an image:
+
+```
+// Import SDL2 and SDL_image
+// Both work with Emscripten
+import bindbc.sdl;
+import bindbc.sdl.image;
+import core.stdc.stdio : printf; // printf works in Emscripten, too
+
+// Function declarations for the main loop
+alias em_arg_callback_func = extern(C) void function(void*) @nogc nothrow;
+extern(C) void emscripten_set_main_loop_arg(em_arg_callback_func func, void *arg, int fps, int simulate_infinite_loop) @nogc nothrow;
+extern(C) void emscripten_cancel_main_loop() @nogc nothrow;
+
+// Log output
+void logError(size_t line = __LINE__)() @nogc nothrow {
+    printf("%d:%s\n", line, SDL_GetError());
+}
+
+struct MainLoopArguments {
+    SDL_Renderer* renderer;
+    SDL_Texture* texture;
+}
+
+// Language features restricted with @nogc and nothrow
+extern(C) int main(int argc, const char** argv) @nogc nothrow {
+    // Initialise SDL
+    if(SDL_Init(SDL_INIT_VIDEO) != 0) {
+        logError();
+        return -1;
+    }
+    scope(exit) SDL_Quit();
+
+    // Initialise SDL_image (with PNG support)
+    if(IMG_Init(IMG_INIT_PNG) != IMG_INIT_PNG) {
+        logError();
+        return -1;
+    }
+    scope(exit) IMG_Quit();
+
+    // Make the window and its renderer
+    SDL_Window* window;
+    SDL_Renderer* renderer;
+    if(SDL_CreateWindowAndRenderer(640, 480, SDL_WINDOW_SHOWN, &window, &renderer) != 0) {
+        logError();
+        return -1;
+    }
+    scope(exit) {
+        SDL_DestroyRenderer(renderer);
+    SDL_DestroyWindow(window);
+    }
+
+    // Load image file
+    auto dman = IMG_Load("images/dman.png");
+    if(!dman) {
+        logError();
+        return -1;
+    }
+    scope(exit) SDL_FreeSurface(dman);
+
+    // Make a texture from the image
+    auto texture = SDL_CreateTextureFromSurface(renderer, dman);
+    if(!texture) {
+        logError();
+        return -1;
+    }
+    scope(exit) SDL_DestroyTexture(texture);
+
+    // Start the image main loop
+    auto arguments = MainLoopArguments(renderer, texture);
+    emscripten_set_main_loop_arg(&mainLoop, &arguments, 60, 1);
+    return 0;
+}
+
+extern(C) void mainLoop(void* p) @nogc nothrow {
+    // Get arguments
+    auto arguments = cast(MainLoopArguments*) p;
+    auto renderer = arguments.renderer;
+    auto texture = arguments.texture;
+
+    // Clear background
+    SDL_SetRenderDrawColor(renderer, 0x00, 0x00, 0x00, 0x00);
+    SDL_RenderClear(renderer);
+
+    // Texture image
+    SDL_RenderCopy(renderer, texture, null, null);
+    SDL_RenderPresent(renderer);
+
+    // End of loop iteration
+    emscripten_cancel_main_loop();
+}
+```
+
+#### Building
+
+Now building is the tricky bit.
+
+##### `dub.json`
+
+Here’s the `dub.json` I made through trial and error. It runs the whole build from D to WebAssembly.
+
+```
+{
+    "name": "emdman",
+    "authors": [
+        "outland.karasu@gmail.com"
+    ],
+    "description": "A minimal emscripten D man demo.",
+    "copyright": "Copyright © 2018, outland.karasu@gmail.com",
+    "license": "BSL-1.0",
+    "dflags-ldc": ["--output-bc", "-betterC"], // Settings for bitcode output
+    "targetName": "app.bc",
+    "dependencies": {
+        "bindbc-sdl": "~>0.4.1"
+    },
+    "subConfigurations": {
+        "bindbc-sdl": "staticBC" // Statically-linked, betterC build
+    },
+    "versions": ["BindSDL_Image"], // Use SDL_image
+
+    // Run the Emscripten compiler after generating bitcode
+    // * Disable optimisations
+    // * Enable WebAssembly
+    // * Use SDL+SDL_image (with PNG)
+    // * Set web-only as the environment
+    // * Embed image file(s)
+    // * Generate HTML for running in browser
+    "postBuildCommands": ["emcc -v -O0 -s WASM=1 -s USE_SDL=2 -s USE_SDL_IMAGE=2 -s SDL2_IMAGE_FORMATS='[\"png\"]' -s ENVIRONMENT=web --embed-file images -o dist/index.html app.bc"]
+}
+```
+
+##### Switch to 32b (x86) code generation
+
+Compiling with 64b “worked” but I got a warning about different data layouts:
+
+```
+warning: Linking two modules of different data layouts: '/tmp/emscripten_temp_WwvmL5_archive_contents/mulsc3_20989819.c.o' is 'e-p:32:32-i64:64-v128:32:128-n32-S128' whereas '/src/app.bc' is 'e-m:e-i64:64-f80:128-n8:16:32:64-S128'
+
+warning: Linking two modules of different target triples: /tmp/emscripten_temp_WwvmL5_archive_contents/mulsc3_20989819.c.o' is 'asmjs-unknown-emscripten' whereas '/src/app.bc' is 'x86_64-unknown-linux-gnu'
+```
+
+Apparently Emscripten is basically for 32b code. Using mismatched pointer sizes sounds like a pretty bad idea, so I added this `/var/lib/dub/settings.json` to the Dockerfile:
+
+```
+{
+        "defaultArchitecture": "x86", // Set code generation to 32b
+        "defaultCompiler": "ldc" // Use LDC by default
+}
+```
+
+There’s an [open issue for documenting `dub`’s `settings.json`][10].
+
+##### Remove debug information
+
+Emscripten gave the following error when I ran a normal build with `dub`:
+
+```
+shared:ERROR: Failed to run llvm optimizations:
+```
+
+It looks like there’s [an issue related to debugging information][11]. I worked around it by using `dub --build=release`.
+
+### Results
+
+After lots of trial and error, I finally succeeded in getting my demo to run in a browser. Here’s how it looks:
+
+![Meet D-Man \(Demo\)][12]
+
+The Emscripten+D dev environment isn’t as stable as a normal dev environment. For example, rendering didn’t work if I used `SDL_LowerBlit` instead. But here’s D-Man in a browser.
+
+--------------------------------------------------------------------------------
+
+via: https://theartofmachinery.com/2018/12/20/emscripten_d.html
+
+作者：[Simon Arneaud][a]
+选题：[lujun9972][b]
+译者：[译者ID](https://github.com/译者ID)
+校对：[校对者ID](https://github.com/校对者ID)
+
+本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出
+
+[a]: https://theartofmachinery.com
+[b]: https://github.com/lujun9972
+[1]: https://github.com/Ace17/dscripten
+[2]: https://github.com/CyberShadow/dscripten-tools
+[3]: https://wiki.dlang.org/Generating_WebAssembly_with_LDC
+[4]: https://github.com/outlandkarasu-sandbox/emdman
+[5]: https://qiita.com/outlandkarasu@github/items/15e0f4b6d1b2a0eab846
+[6]: http://kripken.github.io/emscripten-site/
+[7]: https://wiki.dlang.org/LDC
+[8]: https://github.com/BindBC/bindbc-sdl
+[9]: https://hub.docker.com/r/trzeci/emscripten/
+[10]: https://github.com/dlang/dub/issues/1463
+[11]: https://github.com/kripken/emscripten/issues/4078
+[12]: /images/emscripten_d/d-man-browser.png