emscripten-core / emscripten-core/emscripten
Tutorial is confusing; error handling could be better
- Dominant language
- C++
- Stars
- 27.6k
- Forks
- 3.6k
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 105
Description
Thanks for emscripten, I've finally achieved liftoff, and working on my project. My letter today is fairly long, but has a lot of constructive suggestions, for the tutorial and the code, from a new-user perspective. Read it carefully! Because I want enscriptem to succeed, and the more people who can use it, the better. I'm a programmer who does a lot of ui/ux and tech writing.
One thing that took me a few hours time was that your tutorial was so confusing. It's not like you don't have enough documentation - it's more like there's too much. Too much, at least, for a tutorial. Every step of the way, there's three or four ways to do everything. I pick one way, but something doesn't work cuz method C, above, doesn't work with method 2, below, and I have to keep reading stuff to figure out why.
A tutorial should make someone successful, ASAP, without fail. No decisions, step 1 2 3, and it works the first time. The details can come later, after I have something working. All the stuff you've written is good, but it's all reference material, not tutorial. I'm a new user; I want to try it in isolation before I smoosh it into my larger app. Take the Download & Install page https://emscripten.org/docs/getting_started/downloads.html . The first thing, it tells you about two other ways to do it besides what's on the page.
- build Emscripten from source
- install emscripten using the "unofficial" packages
Why would I care for either of these? I'm in foreign territory, I have no idea what to do, why would I take unnecessary chances? I can do that later, after I've learned to doggy paddle.
400 words into the Emscripten Tutorial, you finally get down to business: a Hello World program. We don't need to dig up the file you've hidden in your directory jungle. And we don't need a copyright - YOU don't need a copyright that takes up 77% of the file. It's 4 friggin lines, and every C programmer has memorized it:
#include
int main() {
printf("hello, world!\n");
}
I'd be happy to type it in by hand (as a tutorial reader), but copying from your web page and pasting it into a file is easier.
In the 'Generating HTML' section, you give us a command to make an html file. Then, you turn around and tell us that it won't work. (After I've already tried and it didn't work. And I said to myself, emscripten's so difficult!) Make some way for the Hello World tutorial to work immediately, in one step, including file: protocol.
After failing that, you tell me to compile this SDL program. I don't even know what SDL is, and why should I care. I've already done SVG and WebGL. Yawn. I guess some other people would like it. More reference material.
Far more useful would be if I could get hello_world.c to work in my React app. It's so simple! should be easy. I try copying the
Thats all I need, right? (yeah it is, but I was tempted to copy out the 3.6k of JS code just above it... PS: you can get rid of the type= attribute, that's the default, it'll work fine.) I paste it into React's index.html file, but I get these errors:
CompileError: WebAssembly.instantiate(): expected magic word 00 61 73 6d, found 3c 21 44 4f
actually, 3 or 4 copies of the same message, but whatever. Why is it doing this at Javascript Compile time? (really it was at wasm compile time - update your message to be more specific that its wasm compile time, because React COMPILES JSX to JS - long story. Coffeescript COMPILES to JS. Typescript COMPILES to JS.) I recognized 00 61 73 6d as the start of the wasm file. (actually what happened: no hello.wasm file, so I get an HTML error msg file that starts with **
Contributor guide
Assessment
This issue has not been assessed yet.