emscripten-core / emscripten-core/emscripten

Tutorial is confusing; error handling could be better

Open
#14,265 1 comment 0 reactions 0 assignees View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.