Confirmed users
228
edits
MDN/Development/Emscripten: Difference between revisions
→What content should it have?
No edit summary |
|||
| (15 intermediate revisions by the same user not shown) | |||
| Line 6: | Line 6: | ||
* Run code originated in languages like Python on the web as well, for example by compiling CPython from C to JavaScript | * Run code originated in languages like Python on the web as well, for example by compiling CPython from C to JavaScript | ||
This is a really cool and very useful technology, and it is essential for the success of some of Mozilla's current initiatives, such as [https://developer.mozilla.org/en-US/docs/Games web gaming]. But the uses of Emscripten go beyond just building amazing games, therefore I have decided that Emscripten should have its own landing page on MDN, covering Emscripten in a more | This is a really cool and very useful technology, and it is essential for the success of some of Mozilla's current initiatives, such as [https://developer.mozilla.org/en-US/docs/Games web gaming]. But the uses of Emscripten go beyond just building amazing games, therefore I have decided that Emscripten should have its own landing page on MDN, covering Emscripten in a more complete fashion. | ||
[https://github.com/kripken/emscripten/wiki Emscripten currently has a wiki on github] that contains some great content, but this content could use some updating and reorganization, and we have lots of other ideas for content too, to tell the full story of how useful Emscripten is to interested parties such as C++ developers. | [https://github.com/kripken/emscripten/wiki Emscripten currently has a wiki on github] that contains some great content, but this content could use some updating and reorganization, and we have lots of other ideas for content too, to tell the full story of how useful Emscripten is to interested parties such as C++ developers. | ||
| Line 14: | Line 14: | ||
==Where will this project live?== | ==Where will this project live?== | ||
The | The main host for this docs project will be an MDN zone, with its landing page at https://developer.mozilla.org/en-US/docs/Emscripten. | ||
We will also have a professional looking external site, say at emscripten.org, with nice links to demos etc., maybe a dozen pages all in all. This will be the "landing page", but will link back to MDN for the meat of the content. | |||
==What content should it have?== | ==What content should it have?== | ||
| Line 22: | Line 24: | ||
<blockquote>My experience and perspective is mainly from the "Game developer who has written a native game in C/C++ for Android/iOS/PC and wants to port it to FxOS/browser" viewpoint.</blockquote> | <blockquote>My experience and perspective is mainly from the "Game developer who has written a native game in C/C++ for Android/iOS/PC and wants to port it to FxOS/browser" viewpoint.</blockquote> | ||
Proposed structure | |||
An introduction to Emscripten, including how it works, how to get it set up and start | https://developer.mozilla.org/en-US/docs/Emscripten | ||
*- Introducing Emscripten | |||
*- Web abilities and limitations | |||
* Product manual (covers latest version, currently 1.7.8) | |||
**- Download and install | |||
**- Workflow and tools | |||
**- Techniques | |||
**- Reference | |||
*- Demos | |||
*- Older product manual versions | |||
**- 1.7.1 | |||
***- Download and install | |||
***- Workflow and tools | |||
***- Techniques | |||
***- Reference | |||
**- 1.5.1 | |||
***- Download and install | |||
***- Workflow and tools | |||
***- Techniques | |||
***- Reference | |||
===Introducing Emscripten (always cover the latest version of Emscripten)=== | |||
An introduction to Emscripten, including how it works, how to get it set up and start working with it, and some beginner's tutorials. Throughout this section we can reference more detailed guides in later sections. | |||
* What is Emscripten and how does it work? | * What is Emscripten and how does it work? | ||
* The nature of Emscripten compiled JS - brief summary | |||
** non-threading | |||
** async main loop | |||
** async file loading | |||
** memory model | |||
** networking | |||
** performance | |||
* Your first steps with Emscripten | * Your first steps with Emscripten | ||
** Download and install | ** Download and install (https://github.com/kripken/emscripten/wiki/Emscripten-SDK, https://github.com/kripken/emscripten/wiki/Getting-started-on-Mac-OS-X, https://github.com/kripken/emscripten/wiki/Getting-Started-on-Ubuntu-12.10, https://github.com/kripken/emscripten/wiki/Using-Emscripten-on-Windows) | ||
** Hello world | ** Hello world (https://github.com/kripken/emscripten/wiki/Tutorial, present A minimal GL rendering sample that shows how to get stuff up and running | ||
*** Generating the code | *** Generating the code | ||
*** The asm.js module | *** The asm.js module | ||
| Line 36: | Line 67: | ||
*** linking | *** linking | ||
*** Emscripten boilerplate | *** Emscripten boilerplate | ||
*** Quick guide to Emscripten compiling, including some essential compiler flags | |||
* Quickstart guide to putting Emscripten in your toolchain | |||
* Next steps | |||
** Emscripten APIs | |||
** Working out what C++ stuff is supported well in Emscripten, and what isn't | |||
** What problems should you solve on the C++ side? | |||
** What should be written in JS and glued on. How is this done? | |||
** https://github.com/kripken/emscripten/wiki/Library-Support ? | |||
** https://github.com/kripken/emscripten/wiki/CodeGuidelinesAndLimitations | |||
** Solving specific problems (mini case studies - these don't need to be long, just present minimal examples and link to further resources in the techniques section?) | |||
*** 2d graphics | |||
*** 3d graphics | |||
*** sound | |||
*** file-system access | |||
*** input | |||
*** networking | |||
===Web abilities and limitations=== | ===Web abilities and limitations (probably doesn't need to be version-specific)=== | ||
This could be a single article but may well be multiple articles under a single section as the document resource grows. The main purpose here is to provide native developers trying to research the feasibility of running their project on the web with some answers. | This could be a single article but may well be multiple articles under a single section as the document resource grows. The main purpose here is to provide native developers trying to research the feasibility of running their project on the web with some answers. | ||
* How does the web differ to | * How does the web differ to running native code? (https://github.com/kripken/emscripten/wiki/Emscripten-browser-environment) | ||
** non-threading | ** non-threading | ||
** async main loop | ** async main loop | ||
** async file loading | ** async file loading | ||
** memory model | ** memory model | ||
** https://github.com/kripken/emscripten/wiki/Browser-limitations | |||
**networking | **networking | ||
** performance | ** performance | ||
| Line 56: | Line 104: | ||
** What does Emscripten rely on? | ** What does Emscripten rely on? | ||
** What browsers currently support this combination? | ** What browsers currently support this combination? | ||
=== | ===Download and install (could be versioned)=== | ||
* Win | |||
* Mac | |||
* Linux | |||
* Troubleshooting | |||
* Other useful tool links | |||
===Workflow and tools (could be versioned)=== | |||
As a native developer, how can I get up and running with Emscripten, including it as an additional development target that fits into my existing toolchain? | As a native developer, how can I get up and running with Emscripten, including it as an additional development target that fits into my existing toolchain? | ||
| Line 69: | Line 120: | ||
** An ideal toolchain | ** An ideal toolchain | ||
** Other alternatives | ** Other alternatives | ||
* Emscripten in your build system (https://github.com/kripken/emscripten/wiki/Building-Projects) | |||
* Emscripten in your build system | ** https://github.com/kripken/emscripten/wiki/Code-Generation-Modes | ||
** Reworking your existing build system to target emscripten | ** Reworking your existing build system to target emscripten | ||
** Co-maintaining both native and emscripten targets simultaneously | ** Co-maintaining both native and emscripten targets simultaneously | ||
| Line 76: | Line 127: | ||
** Installable app packaging | ** Installable app packaging | ||
** Mobile runtime quirks | ** Mobile runtime quirks | ||
* Debugging Emscripten code output | * Debugging Emscripten code output (https://github.com/kripken/emscripten/wiki/Debugging) | ||
===Techniques for working with Emscripten=== | ===Techniques for working with Emscripten (could be versioned)=== | ||
More detailed tutorials than you got with the hello world section in the introductory material. Generally these should help developers solve specific problems with their code, and porting it across. It might be an idea to, at each point, say what C++ component is being used, and what JavaScript API/construct it is being compiled into, making it easier to understand what is going on whether you are a C++ person or a JavaScript person. | More detailed tutorials than you got with the hello world section in the introductory material. Generally these should help developers solve specific problems with their code, and porting it across. It might be an idea to, at each point, say what C++ component is being used, and what JavaScript API/construct it is being compiled into, making it easier to understand what is going on whether you are a C++ person or a JavaScript person. | ||
| Line 88: | Line 139: | ||
** OpenAL | ** OpenAL | ||
** EGL (see https://github.com/kripken/emscripten/wiki/EGL-Support-in-Emscripten for a good example) | ** EGL (see https://github.com/kripken/emscripten/wiki/EGL-Support-in-Emscripten for a good example) | ||
** OPENGL (https://github.com/kripken/emscripten/wiki/OpenGL-support) | |||
** GLES2 | ** GLES2 | ||
** https://github.com/kripken/emscripten/wiki/GC | |||
** https://github.com/kripken/emscripten/wiki/Linking | |||
** others... | ** others... | ||
* | * Architecting around common problems - provide a case study for each? (Currently we do have some examples of "how do I do X in Emscripten" as part of the unit test suite, but naturally that's not a good format for reading as a documentation/learning material. Some of those could be hoisted or used as a basis for a better set of example apps.) | ||
** Common C++ libraries/technologies that Emscripten doesn't handle so well, provide an article for each? | ** Common C++ libraries/technologies that Emscripten doesn't handle so well, provide an article for each? | ||
** non-threading | ** non-threading | ||
** async main loop (async compilation is already covered at | ** async main loop (async compilation is already covered at https://developer.mozilla.org/en-US/docs/Games/Techniques/Async_scripts. Perhaps include some extra explanation about what's going on inside the JS engine?) | ||
** async file loading (https://github.com/kripken/emscripten/wiki/Filesystem-Guide, https://github.com/kripken/emscripten/wiki/Filesystem-API) | |||
** async file loading | |||
** memory model | ** memory model | ||
** networking | ** networking | ||
** performance | ** performance | ||
** https://github.com/kripken/emscripten/wiki/Asm-pointer-casts | |||
** https://github.com/kripken/emscripten/wiki/Synchronous-Virtual-XHR-Backed-File-System-Usage | |||
* Emscripten APIs (see https://github.com/kripken/emscripten/blob/master/system/include/emscripten/emscripten.h) | * Emscripten APIs (see https://github.com/kripken/emscripten/blob/master/system/include/emscripten/emscripten.h) | ||
** | ** Embind (https://github.com/kripken/emscripten/wiki/embind) | ||
** y | ** y | ||
** z | ** z | ||
* Combining handspun JavaScript with Emscripten code | * Combining handspun JavaScript with Emscripten code (https://github.com/kripken/emscripten/wiki/Interacting-with-code) | ||
** Developing a JS library to solve problem X | ** Developing a JS library to solve problem X | ||
** Gluing it to your Emscripten application | ** Gluing it to your Emscripten application | ||
* Benchmarking, profiling and optimization | * Benchmarking, profiling and optimization | ||
** e.g. minimizing data sizes | ** e.g. minimizing data sizes (https://github.com/kripken/emscripten/wiki/Compressing-Downloads) | ||
** optimize web transfers? | ** optimize web transfers? | ||
** optimizing generated code (https://github.com/kripken/emscripten/wiki/Optimizing-Code, https://github.com/kripken/emscripten/wiki/Optimizing-the-source-code) | |||
* Creating the launch experience | * Creating the launch experience | ||
** Creating a start page | ** Creating a start page | ||
** Launching the application into full screen or windowed mode. | ** Launching the application into full screen or windowed mode. | ||
===Reference documentation=== | ===Reference documentation (could be versioned)=== | ||
* Compiler reference | * Compiler reference | ||
** Compiler flags list (The most important compiler flags are mentioned in https://github.com/kripken/emscripten/wiki/Tutorial and https://github.com/kripken/emscripten/wiki/Optimizing-Code) | ** Compiler flags list (The most important compiler flags are mentioned in https://github.com/kripken/emscripten/wiki/Tutorial and https://github.com/kripken/emscripten/wiki/Optimizing-Code) | ||
* Links to relevant C/C++ library documentation, with | * Links to relevant C/C++ library documentation, with annotations relevant to Emscripten usage | ||
* Links to relevant JS/API documentation, with annotations relevant to Emscripten usage | * Links to relevant JS/API documentation, with annotations relevant to Emscripten usage | ||
* Links to other relevant docs - Graphics, GLES2? | * Links to other relevant docs - Graphics, GLES2? | ||
* Links to relevant tool documentation | * Links to relevant tool documentation | ||
* Emscripten FAQ (https://github.com/kripken/emscripten/wiki/FAQ) | |||
== | ===Demos (does this need to be versioned?)=== | ||
* a | |||
* b | |||
* c | |||
* etc. | |||
==What should we talk to?== | ==What should we talk to?== | ||
Alon, Jukka, Vlad, Martin Best, Dave Herman, Luke Wagner, the rest of the games team! | |||