Fix GEMSTEP Installation for M1 (ARM) Macs

[dsriseah]

GEMSTEP does not install correctly on M-series Macintoshes as they use the ARM CPU architecture, and the version of NodeJS that this codebase is tied to does not know how to work with it correctly and leads to numerous mysterious errors.

The workaround is to force Intel i386 mode with the arch command, but you have to do it correctly from a fresh installation. This pull request adds additional detection code to gem-srv that will prompt users to correct the problem. It's suggested that this is added to the installation instruction as well, since Intel Macs are no longer being produced.

TEST 1: GATHER INFO

There are four important contexts to check for the runtime environment, which you can grab by running this command line:

node -v; arch; echo $0; git branch --show-current; nvm which

The output should be:

v14.21.3
i386
/bin/zsh (or /bin/bash)
( whatever branch you are on )
Found '.nvmrc' with version <v14.21.3>
( other stuff )

If the version and architecture lines do not match, then your terminal shell is misconfigured and npm run gem may fail. The next test will detect and prompt you about the issues.

TEST 2: DETECT ENVIRONMENT MISMATCH

The gem-run.js file now checks both the node version and the cpu architecture for matches.

npm run gem

WHEN EVERYTHING CHECKS OUT

WRONG NODE VERSION

WRONG ARCHITECTURE

TEST 3: RUN GEMSTEP NORMALLY

To make sure everything is still working correctly, do your normal GEMSTEP development and runtime activities and report any issues!

1. Does your current student activity still work as expected?
2. Does the source code you are working on still seem to run correct?

TEST 4: ENABLE AUTOFORCING NVM SCRIPT

The project's .vscode folder (normally hidden) contains a script called check_env which will try to automatically force the arch command and apply nvm use for you. It works only on Macs and ensures that i386 architecture is set AND that the official Node version is being used as defined in the .nvmrc file

To test, you have to uncomment a section in the gsgo.code-workspace and then start a fresh integrated terminal session from VSCODE. This script does not run outside of VSCODE's environment.

1. open the file gsgo/gsgo.code-workspace
2. At the bottom of this file, look for the following block of text
3. Uncomment the line "terminal.integrated.defaultProfile.osx": "x86 macos" and save the file.
4. Under the VSCODE File menu, pick Close Workspace. If the option is disabled, you were not using the official project workspace and you should start using it to ensure compatibility with settings inside it.
5. Quit VSCode completely.
6. Reopen VSCode, and from the File menu choose Open Workspace. Find the gsgo.code-workspace file and open it.
7. Open the terminal window with CTRL-TILDE (~) and you should see something like this:
8. The message may vary and tell you to quit/restart again.

You can rerun the information-gathering commands again to confirm that the correct node version and architecture is running:

node -v; arch; echo $0; git branch --show-current; nvm which

9. Every time you quit and restart visual studio code with the gsgo.code-workspace, your settings will be enforced so you don't have to remember to do it.

BONUS TEST: MANUAL INSTALL ON NEW MAC

Using the existing dev-next branch, try to configure from scratch manually without the new code and see if it works! Here is the quickie setup.

_Note that the default gsgo and art-assets branches may not be working, so you might need to find out what the 'latest working set' is from someone. For example, at the time of this writing dev-next is tuned for a specific art-assets branch called fall_2023_cross-site_

git clone git@github.com:theRAPTLab/gsgo.git  
cd gsgo
git checkout dev-next

echo '{"GS_ASSETS_PROJECT_ROOT":"art-assets"}' > gs_packages/gem-srv/config/local-settings.json

mkdir gs_assets
cd gs_assets
git clone git@github.com:theRAPTLab/art-assets.git
cd ..

Next you'll manually check the environment

node -v; arch; echo $0; git branch --show-current; nvm which

Then you'll force the environment to be correct:

arch -x86_64 $0
nvm use

Then you'll try running the build and hopefully everything just works

npm ci
npm run bootstrap
npm run gem

Open up a browser window to http://localhost

[benloh]

Confirmed everything works. A few minor clarifications to make sure these things don't matter.

intel tests

• Confirmed that current Intel mac still runs.
• Note "4. Under the VSCODE File menu, pick Close Workspace" instructions, I wasn't using the workspace, so I had to first quit VSCode, start by opening the workspace, quit again, and start a second time to get it to load. Otherwise, VSCode complains (after opening the VSCode terminal the first time after uncommenting "terminal.integrated.defaultProfile.osx": "x86 macos"):

  vsenv: VISUAL STUDIO CODE INTEGRATED TERMINAL DETECTED
     (nvm) current version and alias detected setting: node \e[34;1mv14.21.3\e[0m
  vsenv: \e[1mkill/restart VSCODE for nvm alias default to take effect!\e[0m
     this shell is using version \e[34;1mv18.16.0\e[0m until you do
     alternatively, type \e[33;1mnvm use v14.21.3\e[0m to use it now

M1 Tests

• Interestingly my version of git is 2.15.0 and does not have --show-current as an option for the git branch command (using /usr/local/bin/git).
• Confirmed that "MANUAL INSTALL ON NEW MAC" works. (NOTE to self: have to check out dev-ds/build-arm64-warn to open workspace and test VSCode terminal)
• Checking the intended behavior here: if v14.21.3 is NOT installed and I open the workspace, I get the message:

  ! WARNING: Version ‘v14.21.3’ does not exist.
  N/A: version “v14.21.3 -> N/A” is not yet installed.
  You need to run “nvm install v14.21.3" to install it before using it.
  vsenv: VISUAL STUDIO CODE INTEGRATED TERMINAL DETECTED
     (nvm) and alias detected setting: node v14.21.3
  vsenv: kill/restart VSCODE for nvm alias default to take effect!
     this shell is using version v14.15.1 until you do
     alternatively, type nvm use v14.21.3 to use it now
  loh@Bens-MacBook-Air gsgo %

  and I have to run nvm install v14.21.3 first before VSCode terminal will correctly detect and use the right node version. (In other words, v14.21.3 is not automatically installed if it hasn't already been installed).

[benloh]

One more minor note: GS_ASSETS_PROJECT_ROOT = 'art-assets' is currently defined in gsgo-settings.js, so strictly speaking, there is no need to modify the local-settings.json file in order to get a base install working.

That said, we probably want to make sure the art-assets repo has a working project by default as the current branch defaults to a broken project.

[benloh]

@jdanish You don't need to test this, but just noting it here FYI. I've confirmed that this all works with both Intel and ARM macs and we'll be merging this. So you should be aware that this is happening in case it also affects VU installs. Also, I want to note that you should update art-assets to ensure that anyone using the system has a reasonable chance of finding a working project -- see art-assets #2.

[daveseah]

@benloh followup notes:

• UPDATE: I rewrote the shell check_env to NOT execute nvm alias default because this can possibly break other projects if they are not managed.

• For Intel Note 4: It's not clear to me that you are reporting an error with "VSCode complains". I think you might be saying that you had to open the workspace (then you uncommented) then you had to startup to test?

• Is your terminal for Intel text actually not showing colors? This is what I see in your test report above:

On a side note, the creation of the local-settings.json file is probably a good thing to override the built-in defaults, as people should not be editing them in the first place? I like how this step is explicitly tied to the downloading of the art-assets repo.

[daveseah]

Incidentally, if you set your screen capture output to "clipboard", you can easily snip bits of the screen and paste it directly into Github Comments and Pull Requests. You set the output with CMD-SHIFT-5 and editing the options; then after that it will also affect CMD-SHIFT-4 when you are doing snips of the screen.