diff --git a/README.md b/README.md index a66badff..29811839 100644 --- a/README.md +++ b/README.md @@ -44,25 +44,120 @@ your operating system from the #### Mac OS -- Unzip `mac-release.zip` from your `Downloads/` folder -- Double-click on `orca-X.Y.Z.dmg` file, that should open an installation window -- Drag the orca icon into _Applications_ -- In finder, go to the `Applications/` folder -- Right-click on the orca icon and click on _Open_, this should open an _Installation Succeeded_ window -- Open the terminal and start using Orca! +- Unzip the `mac-release.zip` file. +- Double-click on the `orca-X.Y.Z.dmg` file. This will open an installation window. +- Drag the orca icon into the `Applications` folder. +- Open finder and navigate to the `Applications/` folder. +- Right-click on the orca icon and select _Open_ from the context menu. +- A password dialog will appear asking for permission to add orca to your system `PATH`. +- Enter you password and click _OK_. +- This should open an _Installation Succeeded_ window. +- Open a new terminal and verify that the orca executable is available on your `PATH`. + +``` +$ which orca +/usr/local/bin/orca + +$ orca --help +Plotly's image-exporting utilities + + Usage: orca [--version] [--help] [] + ... +``` #### Windows -- Extract the `window-release.zip` file -- In the `release` folder, double-click on `orca Setup X.Y.Z`, this will create an orca icon on your Desktop -- Right-click on the orca icon, then click on _Properties_ and copy the _Starts in_ field -- In the command prompt, run `PATH %PATH%;` +- Extract the `windows-release.zip` file. +- In the `release` folder, double-click on `orca Setup X.Y.Z`, this will create an orca icon on your Desktop. +- Right-click on the orca icon and select _Properties_ from the context menu. +- From the _Shortcut_ tab, copy the directory in the _Start in_ field. +- Add this _Start in_ directory to you system `PATH` (see below). +- Open a new Command Prompt and verify that the orca executable is available on your `PATH`. + +``` +> orca --help +Plotly's image-exporting utilities + + Usage: orca [--version] [--help] [] + ... +``` + +##### Windows References + - How to set the path and environment variables in Windows: https://www.computerhope.com/issues/ch000549.htm #### Linux -- Run `$ chmod +x orca-X.Y.Z-x86_64.AppImage` -- Add it to your `$PATH` +- Make the orca AppImage executable. + +``` +$ chmod +x orca-X.Y.Z-x86_64.AppImage +``` + +- Create a symbolic link named `orca` somewhere on your `PATH` that points +to the AppImage. + +``` +$ ln -s /path/to/orca-X.Y.Z-x86_64.AppImage /somewhere/on/PATH/orca +``` + +- Open a new terminal and verify that the orca executable is available on your `PATH`. + +``` +$ which orca +/somewhere/on/PATH/orca + +$ orca --help +Plotly's image-exporting utilities + + Usage: orca [--version] [--help] [] + ... +``` + +##### Linux Troubleshooting: Cannot open shared object +The Electron runtime depends a several common system libraries. These +libraries are pre-installed in most desktop Linux distributions +(e.g. Ubuntu), but are not pre-installed on some server Linux distributions +(e.g. Ubuntu Server). If a shared library is missing, you will see an error +message like: + +``` +$ orca --help +orca: error while loading shared libraries: libgtk-x11-2.0.so.0: +cannot open shared object file: No such file or directory +``` + +These additional dependencies can be satisfied by installing: + - The `libgtk2.0-0` and `libgconf-2-4` packages from your distribution's + software repository. + - The `google-chrome-stable` package from the [Google Linux Software + Repository](https://www.google.com/linuxrepositories/). + +##### Linux Troubleshooting: Headless server configuration +The Electron runtime requires the presence of an active X11 display server, +but many server Linux distributions (e.g. Ubuntu Server) do not include X11 +by default. If you do not wish to install X11 on your server, you may +install and run orca with Xvfb instead. + +On Ubuntu Server, you can install Xvfb like this: +``` +$ sudo apt-get install xvfb +``` + +To run orca under Xvfb, replace the symbolic link suggested above with a shell +script that runs the orca AppImage executable using the `xvfb-run` command. + +``` +#!/bin/bash +xvfb-run /path/to/orca-X.Y.Z-x86_64.AppImage "$@" +``` + +Name this shell script `orca` and place it somewhere or your system `PATH`. +##### Linux References + - How to add directory to system path in Linux: https://www.computerhope.com/issues/ch001647.htm + - AppImage: https://appimage.org/ + - Xvfb: https://en.wikipedia.org/wiki/Xvfb + ## Quick start From the command line: diff --git a/bin/orca_electron.js b/bin/orca_electron.js index 6ae41e50..71e45bd3 100644 --- a/bin/orca_electron.js +++ b/bin/orca_electron.js @@ -44,21 +44,48 @@ if (process.platform === 'darwin' && process.argv.length === 1) { 'To create your first image, open a terminal and run:\n\norca graph \'{ "data": [{"y": [1,2,1]}] }\' -o fig.png' } - const source = path.join(__dirname, 'orca.sh') - const target = '/usr/local/bin/orca' - - if (!fs.existsSync(target)) { - try { - execSync(`cp ${source} ${target}`) - } catch (err) { - options.type = 'error' - options.message = 'Installation Failed!' - options.detail = err.message + let showMessage = false + + try { + execSync('which orca') + // Orca is already on the path, nothing to do + } catch (err) { + // Check if this is a standalone installation (not conda or npm) + const standalonePath = '/Applications/orca.app/Contents/MacOS/orca' + if (fs.existsSync(standalonePath)) { + // Now we know that orca is not on the path, but it is installed + // in the /Applications directory. So we'll ask the user if they + // want to add it to the path + const source = path.join(__dirname, 'orca.sh') + const target = '/usr/local/bin/orca' + + if (!fs.existsSync(target)) { + // Build copy command + const copyCmd = `"cp ${source} ${target}"` + + // Use apple script to perform copy so that we can launch a GUI + // prompt for administrator credentials + const prompt = '"Add orca to system PATH (/usr/local/bin)?"' + const cmd = `osascript -e 'do shell script ${copyCmd} with prompt ${prompt} with administrator privileges'` + + try { + execSync(cmd) + showMessage = true + } catch (cmdErr) { + // User cancelled. Nothing more to do + } + } + } else { + options.message = 'Executable in non-standard location' + options.detail = 'No orca executable located at /Applications/orca.app/\nNo changes made' + showMessage = true } } app.on('ready', function () { - dialog.showMessageBox(options) + if (showMessage) { + dialog.showMessageBox(options) + } console.log(HELP) process.exit(options.type === 'error' ? 1 : 0) })