Prerequisites for running examples locally - including extra steps for M1 Mac (Apple silicon)

[sobvan]

Link

https://github.com/visgl/deck.gl/blob/master/docs/get-started/getting-started.md

Description

Generally, I experienced buggy examples if yarn bootstrap was not run in the root of the deck.gl before compiling any example project.
The symptom was that zooming stopped working after an error variable _s is undefined was thrown on the console.

On linux running yarn bootstrap in the root directory solved the above issue, and it was quite straightforward to make it compile. The needed dependencies, however, should be stated in the documentation imho.

On a Mac with an M1 chip, however, yarn bootstrap failed with the error

...
gyp info spawn args [ 'BUILDTYPE=Release', '-C', 'build' ]
  SOLINK_MODULE(target) Release/canvas-postbuild.node
  CXX(target) Release/obj.target/canvas/src/backend/Backend.o
../src/backend/Backend.cc:111:10: warning: address of stack memory associated with local variable 'msg' returned [-Wreturn-stack-address]
  return msg.c_str();
         ^~~
1 warning generated.
  CXX(target) Release/obj.target/canvas/src/backend/ImageBackend.o
  CXX(target) Release/obj.target/canvas/src/backend/PdfBackend.o
In file included from ../src/backend/PdfBackend.cc:1:
In file included from ../src/backend/PdfBackend.h:4:
../src/backend/../closure.h:6:10: fatal error: 'jpeglib.h' file not found
#include <jpeglib.h>
         ^~~~~~~~~~~
1 error generated.
make: *** [Release/obj.target/canvas/src/backend/PdfBackend.o] Error 1
gyp ERR! build error
gyp ERR! stack Error: `make` failed with exit code: 2
...

To fix this, I did the following (found here):

The key for me was to run

arch -arm64 brew install pkg-config cairo pango libpng jpeg giflib librsvg

And run yarn bootstrap like this:

CPLUS_INCLUDE_PATH=/opt/homebrew/include yarn bootstrap

[Pessimistress]

bootstrap is not required to run examples. Can you share the trace stack of that error? yarn start in any example does not minify the bundle, so it's not from the example source.

Thank you for sharing the instructions of bootstrapping on M1. It would be great if you can open a PR and add it to https://github.com/visgl/deck.gl/blob/master/CONTRIBUTING.md#troubleshooting

[sobvan]

I tried to replicate the browser error but I was not able to. Before running the bootstrap and installing the dependencies needed for the bootstrap to successfully finish, I remember this browser error occurring pretty consistently.
I tried it both on an m1 Mac and on a Linux laptop with and x64 processor. I think the error occurred on my linux laptop, too.

I found it also strange, and this is why I started to play around with the project itself, and tried yarn bootstrap.

For the record, I tried the pure-js and the react Mapbox examples.

Now I deleted the whole directory and cloned it from scratch but the error did not appear. I am not familiar at all with the innings of deck.gl, but I find it really strange that installing the depnedencies (I mean os level dependencies) and yarn bootstrap (which I have no idea what it does, but I did observe some native code compiling steps :) ) in the root did solve it.
I also do not know which step fixed the examples for me.

Maybe this is totally unrelated, and I was just being lame, but I do not know how I can screw up with running npm install and npm start in a simple example directory.

The browser error did appear both in safari and brave.

I have even installed a pure ubuntu in a virtual machine to try to reproduce this to no avail. So I guess it was some strange coincidence on my end.

I will go on and create the PR for the M1 Mac related steps.

[Pessimistress]

FWIW the only thing that yarn bootstrap installs globally is puppeteer. I would be very surprised if it affects running the basic examples in any way...

[sobvan]

I have created the pull request. Reading the documentation I still think it would be helpful to add some more guide on installing os level dependencies.

Python

For example on Ubuntu 21.04 (a totally clean one) after installing node, npm and yarn, yarn bootstrap complains about python not being found. Python3 is found however.

error /home/ubuntu-vb/playgorund/deck.gl/node_modules/gl: Command failed.
Exit code: 1
Command: prebuild-install || node-gyp rebuild
Arguments: 
Directory: /home/ubuntu-vb/playgorund/deck.gl/node_modules/gl
Output:
prebuild-install WARN install No prebuilt binaries found (target=16.0.0 runtime=node arch=x64 libc= platform=linux)
gyp info it worked if it ends with ok
gyp info using node-gyp@7.1.2
gyp info using node@16.0.0 | linux | x64
gyp info find Python using Python version 3.9.4 found at "/usr/bin/python3"
(node:2590) [DEP0150] DeprecationWarning: Setting process.config is deprecated. In the future the property will be read-only.
(Use `node --trace-deprecation ...` to show where the warning was created)
gyp info spawn /usr/bin/python3
gyp info spawn args [
gyp info spawn args   '/home/ubuntu-vb/playgorund/deck.gl/node_modules/node-gyp/gyp/gyp_main.py',
gyp info spawn args   'binding.gyp',
gyp info spawn args   '-f',
gyp info spawn args   'make',
gyp info spawn args   '-I',
gyp info spawn args   '/home/ubuntu-vb/playgorund/deck.gl/node_modules/gl/build/config.gypi',
gyp info spawn args   '-I',
gyp info spawn args   '/home/ubuntu-vb/playgorund/deck.gl/node_modules/node-gyp/addon.gypi',
gyp info spawn args   '-I',
gyp info spawn args   '/home/ubuntu-vb/.cache/node-gyp/16.0.0/include/node/common.gypi',
gyp info spawn args   '-Dlibrary=shared_library',
gyp info spawn args   '-Dvisibility=default',
gyp info spawn args   '-Dnode_root_dir=/home/ubuntu-vb/.cache/node-gyp/16.0.0',
gyp info spawn args   '-Dnode_gyp_dir=/home/ubuntu-vb/playgorund/deck.gl/node_modules/node-gyp',
gyp info spawn args   '-Dnode_lib_file=/home/ubuntu-vb/.cache/node-gyp/16.0.0/<(target_arch)/node.lib',
gyp info spawn args   '-Dmodule_root_dir=/home/ubuntu-vb/playgorund/deck.gl/node_modules/gl',
gyp info spawn args   '-Dnode_engine=v8',
gyp info spawn args   '--depth=.',
gyp info spawn args   '--no-parallel',
gyp info spawn args   '--generator-output',
gyp info spawn args   'build',
gyp info spawn args   '-Goutput_dir=.'
gyp info spawn args ]
/bin/sh: 1: python: not found
gyp: Call to 'python commit_id.py check ..' returned exit status 127 while in angle/src/angle.gyp. while loading dependencies of binding.gyp while trying to load binding.gyp
gyp ERR! configure error 
gyp ERR! stack Error: `gyp` failed with exit code: 1
gyp ERR! stack     at ChildProcess.onCpExit (/home/ubuntu-vb/playgorund/deck.gl/node_modules/node-gyp/lib/configure.js:351:16)
gyp ERR! stack     at ChildProcess.emit (node:events:365:28)
gyp ERR! stack     at Process.ChildProcess._handle.onexit (node:internal/child_process:290:12)
gyp ERR! System Linux 5.11.0-16-generic
gyp ERR! command "/home/ubuntu-vb/.nvm/versions/node/v16.0.0/bin/node" "/home/ubuntu-vb/playgorund/deck.gl/node_modules/gl/node_modules/.bin/node-gyp" "rebuild"
gyp ERR! cwd /home/ubuntu-vb/playgorund/deck.gl/node_modules/gl

Installing python-is-python3 with apt fixes this. It would be great, though if deck.gl would work without installing these.

Dependencies for build

Right now for me the only possible way for installing all dependencies was trial and error.
This simple list would help a lot imho:

sudo apt install libgif-dev libpango1.0-dev libcairo2-dev libjpeg-dev xserver-xorg-dev libxext-dev libxi-dev

This is that I found to be needed on ubuntu 21.04. Of course other distors might need slightly different packages, but this would be a good start to include.

[Pessimistress]

The headless-gl dependencies are listed in https://github.com/stackgl/headless-gl#system-dependencies