[Documentation] MacOS 10.15 beginner: docu not correct

[rowild]

Hi, dear emscripten guys!

I wanted to post my observations when installing emscripten on macOS Catalina, for which the explanations in the documentation are not correct (this very likely also concerns other macOS versions (and maybe even Linux?)). This might have to do with a version change that is not yet reflected in the docu (but since I am new to emscripten, I can't say).

Not sure if this is at all useful to you guys – if not, please close this issue. Thank you!

Reminder: With Catalina, zsh is the standard shell (not bash anymore).

My observation relate to mainly this page:
https://emscripten.org/docs/building_from_source/verify_emscripten_environment.html

To check emscripten installation, simply use
emcc --check
(not ./emcc --check)

To run a test, navigate to
cd upstream/emscripten/tests/
(not cd emscripten/<version of emscripten you installed>)

and run
emcc hello_world.cpp
(not ./emcc tests/hello_world.cpp)

Important: While it is essential to remove ./ when using emcc, it is not essential with other commands (like emsdk, which works both ways).

UPDATE
A follow-up question regarding zsh and environment variables:

Does emscripten actually support zsh? The reason I ask is that, as soon as I add source ...emsdk/emsdk_env.sh"' >> $HOME/.zshrc (NOT bash-profile), i keep getting this message:
Setting environment variables: PATH=[...]
The message stems from emsdk.py (line 2727), which checks all kinds of shells, but not for zsh, and fires this message in the context of an error log. This is strange, because I actually did set the env vars and the folders via dot-files like this:

# emscripten.config (included in .zshrc via `source emscripten.config`)

# append to path the ZSH way
path+=/Volumes/_III_/Z_WWW/emsdk
path+=/Volumes/_III_/Z_WWW/emsdk/upstream/emscripten
path+=/Volumes/_III_/Z_WWW/emsdk/node/14.15.5_64bit/bin

export EMSDK=/Volumes/_III_/Z_WWW/emsdk
export EM_CONFIG=/Volumes/_III_/Z_WWW/emsdk/.emscripten
export EMSDK_NODE=/Volumes/_III_/Z_WWW/emsdk/node/14.15.5_64bit/bin/node
export EMSDK_PYTHON=/Volumes/_III_/Z_WWW/emsdk/python/3.9.2-1_64bit/bin/python3

source /Volumes/_III_/Z_WWW/emsdk/emsdk_env.sh

Why do I get an error?

[sbc100]

The "./" in the command line "./emcc --check" is needed when you are checking out emscripten from source and not necessarily adding to the path. I think this is the same for zsh and bash. Those instructions are for folks who are not using emsdk, but have emscripten checked out from git. I do think we could make it more clear perhaps? Perhaps if we instruct folks to add emscripten to their PATH first when we can skip the "./"? But I personally don't add emscripten to my PATH so there are at least some developers who won't want that. Alternatively we could change those commands to <emscripten_root>/emcc .. so they can work for any emscripten location?

[sbc100]

Setting environment variables is not an error as such is just informing you of what its doing.

If you don't do anything else if you use emsdk_env.sh. The following lines are basically duplicating what emsdk_env.sh is doing for you.

path+=/Volumes/_III_/Z_WWW/emsdk
path+=/Volumes/_III_/Z_WWW/emsdk/upstream/emscripten
path+=/Volumes/_III_/Z_WWW/emsdk/node/14.15.5_64bit/bin

export EMSDK=/Volumes/_III_/Z_WWW/emsdk
export EM_CONFIG=/Volumes/_III_/Z_WWW/emsdk/.emscripten
export EMSDK_NODE=/Volumes/_III_/Z_WWW/emsdk/node/14.15.5_64bit/bin/node
export EMSDK_PYTHON=/Volumes/_III_/Z_WWW/emsdk/python/3.9.2-1_64bit/bin/python3

You should either use emsdk_env.sh or do this manual config yourself, but not both. Bear in mind if you do it manually rather then using emsdk_env.sh then your stuff could break if emsdk layout changes in the future.

[rowild]

Thank you for your feedback, @sbc100 !

Does this mean i should NOT include the source /Volumes/_III_/_Z... line to get rid of the terminal message? There is so much more in that file that I thought I need it anyway.

The message is shown every time a terminal window is started, which is disturbing. I assume that when I let the emscripten shell script do all the setup, that message will still appear each and every time, maybe even more verbose. Is there a reason why emscripten prints that message to the console?

As for the use of './': The thing is that is fails when, as you say, the path is set. So it should be mentioned somehow, maybe a simple line would do: "Mac users (and Linux?): Keep in mind that './' is not needed when you add emsdk to your path variables."

[sbc100]

The ./ prefix works as long as you are in the emscripten directory, and fails when you are now, regardless of the PATH content. I agree we should make that more clear somehow. I did recently remove a bunch of the ./ usage from the docs in #14073.. but maybe we could do more.

[sbc100]

The emsdk_env.sh will output message to stderr whenever you run it. Perhaps there is some way it can be run globally, just once, rather than on every new terminal. My memory of how .profile and .bashrc works in this respect is not serving me well but I think its possible. We could also add some kind of --quiet option to emsdk so that when run from a login script it can optionally skip those messages.

[sbc100]

It looks like using ~/.zprofile might be the answer you are looking for to avoid seeing those messages in every new terminal.

[rowild]

I need to remove the prefix everywhere as the screenshot shows. But I do not use .zprofile, but dot files instead, that I seem to import in the wrong place (.zshrc). I will research and test that and report back.

[sbc100]

I believe the .zprofile is the name of the zsh equivalent of .bash_profile just like .zshrc is the equivalent of .bashrc.

I also believe that this is the reason we recommend using .bash_profile over .bashrc.. so that you don't see those messages each time you start a shell.

[rowild]

I moved source /Volumes/_III_/Z_WWW/emsdk/emsdk_env.sh (and ONLY that line, none other that I previously had) first to .zenv (which is the place where best to put paths according to many resources on StackOverflow and zsh) and later to .zprofile. But none of these options suppressed that console messages, which are huge (see screenshot again, please).

I will deactivate emscripten, whenever I do not need it, but I would still like to ask you kindly to document a proper way how to keep emscripten quiet in zsh / oh-m-zsh. - Thank you!