MDN/Development/Emscripten: Difference between revisions

Jump to navigation Jump to search

MDN/Development/Emscripten (view source)

Revision as of 12:59, 25 November 2013

548 bytes removed ,  25 November 2013
no edit summary
No edit summary
No edit summary
Line 31: Line 31:
** Download and install
** Download and install
** Hello world
** Hello world
*** Generating the code
*** The asm.js module
*** The heap
*** linking
*** Emscripten boilerplate


===Web abilities and limitations===
===Web abilities and limitations===
Line 52: Line 57:
** What browsers currently support this combination?
** What browsers currently support this combination?
* C++ landscape support for Emscripten
* C++ landscape support for Emscripten
** Common C++ libraries/technologies that Emscripten handles successfully
** Common C++ libraries/technologies that Emscripten handles successfully (provide links forward to more detailed pages in the techniques section)
** Common C++ libraries/technologies that Emscripten doesn't handle so well
** Common C++ libraries/technologies that Emscripten doesn't handle so well
***What needs to be rewritten in C++
***What needs to be rewritten in C++
Line 69: Line 74:
** Co-maintaining both native and emscripten targets simultaneously
** Co-maintaining both native and emscripten targets simultaneously
** Deploying and running your app on a mobile device
** Deploying and running your app on a mobile device
** Installable app packaging
** Mobile runtime quirks
* Debugging Emscripten code output
* Debugging Emscripten code output


===Techniques for working with Emscripten===
===Techniques for working with Emscripten===


More detailed tutorials than you got with the hello world section in the introductory material.
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.
 
Generally the C++ devs won't be initially familiar with the JS specs, and if they are presented e.g. with the Gamepad API or Web Audio API, they'll reject those docs since they are foremost looking for C/C++ solutions to their problems. This is partly because they have just learned about this Emscripten C/C++ compiler that they are now harnessing, and they are right now getting their initial problems solved in the C/C++ side without a single line of JS. Another reason is that devs might not know the JS syntax at all, or if they do, there's a considerable amount of new C/C++ <-> JS interop machinery that one needs to learn, and how to integrate JS into the native build arch, and so on, so being able to develop against JS side APIs will generally come much later during the porting cycle, when the landscape has been charted sufficiently enough to know that one can't (yet) solve all the problems with just native C/C++ code alone.
 
* C++ libraries supported by Emscripten - for each one, cover writing code that works best with Emscripten compilation
** SDL
** OpenAL
** EGL (see https://github.com/kripken/emscripten/wiki/EGL-Support-in-Emscripten for a good example)
** GLES2
** others...
* Architecing 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?
** non-threading
** async main loop (async compilation is already covered at  (perhaps with
  some extra explanation about what's going on inside the JS engine))
** async file loading
** memory model
** networking
** performance
* Emscripten APIs (see https://github.com/kripken/emscripten/blob/master/system/include/emscripten/emscripten.h)
** x
** y
** z
* Combining handspun JavaScript with Emscripten code
** Developing a JS library to solve problem X
** Gluing it to your Emscripten application
* Benchmarking, profiling and optimization
** e.g. minimizing data sizes
** optimize web transfers?
* Creating the launch experience
** Creating a start page
** Launching the application into full screen or windowed mode.


===Reference documentation===
===Reference documentation===


* 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)
* Links to relevant C/C++ library documentation, with annoatations relevant to Emscripten usage
* Links to relevant C/C++ library documentation, with annoatations 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
(disbelief/solving blockers) 10. I have learned about these hard problems (non-threading, async main loop, async file loading, memory model, networking, performance, ...) that I am now able to relate to my own codebase having attempted a port. What can I do? How do I architect around these problems?
(port development) 11. Where is the reference documentation for C/C++ library/api X in Emscripten?
(port development) 12. Where is the reference documentation for JS library/api/spec X?
(port development) 13. How do I develop a JS library to solve X and glue it to my C/C++ game?
(port development) 14. How do I manage FxOS app packaging and mobile runtime?
(finalization) 15. How do I do benchmarking, profiling and optimizations? How to minimize data sizes and optimize web transfers?
(finalization) 16. How do I interact/glue the C/C++ game experience with the browser environment? Web site development around the game shell page, etc?
Generally the devs are initially not familiar with the JS specs, and if they are presented e.g. with the Gamepad API or Web Audio API, they'll reject those docs since they are foremost looking for C/C++ solutions to their problems. This is partly because they have just learned about this Emscripten C/C++ compiler that they are now harnessing, and they are right now getting their initial problems solved in the C/C++ side without a single line of JS. Another reason is that devs might not know the JS syntax at all, or if they do, there's a considerable amount of new C/C++ <-> JS interop machinery that one needs to learn, and how to integrate JS into the native build arch, and so on, so being able to develop against JS side APIs will generally come much later during the porting cycle, when the landscape has been charted sufficiently enough to know that one can't (yet) solve all the problems with just native C/C++ code alone.
I think an important angle to cover, that we currently have a big glaring hole at in the current Emscripten docs at https://github.com/kripken/emscripten/wiki#technical-documentation is the answers to questions #3, #4 and #11. We should have strong documentation pages on each individual API/library we support directly in Emscripten, since a huge part of the Emscripten work (and one that stands us out most compared to nacl!) goes into making sure that existing C/C++ technologies like SDL, OpenAL, EGL, GLES2, etc. are directly supported. For each of these apis that are there, we should have a page "Support for X in Emscripten", similar to we now have for EGL https://github.com/kripken/emscripten/wiki/EGL-Support-in-Emscripten , since that will help people at the initial feasibility study phase and to deciding positively on whether they will take on the effort to try a port.
A second set of docs we should have more flesh in, is the set of emscripten-specific APIs that we have been developing. We don't have much of those, but generally this header file is the only doc available https://github.com/kripken/emscripten/blob/master/system/include/emscripten/emscripten.h .
Third, the set of big problems that everyone porting a native game will eventually run into (item #10 in the list above). Until we have good fixes on those, we should have good prose-like technical documentation that describes the problems with examples of what will not work, and how to refactor the code so that it is JS-friendly, etc.
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.


==Raw ideas==
==Raw ideas==


==What should we talk to?==
==What should we talk to?==
Chrisdavidmills
Confirmed users
228

edits

Retrieved from "https://wiki.mozilla.org/Special:MobileDiff/773958"

Navigation menu