Notes-on-electron-builder

Notes on Creating Images via ElectronBuilder

We can use Electron Builder to create AppImages for Linux, DMG images for Mac OS X, and an image file to be determined via Windows.

To get AppImage to work on various systems, we need to keep the following in mind:

1. The AppImage needs to include all libraries and other dependencies that are not part of the base systems that the AppImage is intended to run on.
2. The binaries contained in the AppImage need to be compiled on a system not newer than the oldest base system that the AppImage is intended to run on.
3. The AppImage should actually be tested on the base systems that it is intended to run on.

For Mac OS X dmg images, these guidlines don't matter as much, as I understand it, because Mac OS doesn't have the variations that Linux distributions have. If we can test our packages on previous versions of Mac OS X, though, it probably wouldn't hurt, but there should be limits on how far back we should be willing to go.

Similarly, I expect the image compiled for Windows should work fine as well, once we figure out how to create the image.

Theoretically we should be able to compile images for all three platforms on one machine (although Windows images require Wine on Linux to do this, and Mac OS X requires compilation to be done on a Mac OS X computer if we desire to sign the image), but in practice, we generate binary files from Chicken Scheme, which will pretty much require us to either figure out how to cross-compile Chicken Scheme source into binaries (which seems to me that would lead to madness), or we will of necessity have to compile versions using each of the three operating systems.

TODO ITEMS

1. Determine the oldest system we wish to have Electron run on, and build on it. For stupid reasons (ie, I just like Debian) I chose Debian Jesse (which is one less than the current version), but there might be a better choice for a "base" system.
2. Determine which systems we wish to test. IDEALLY, it would be a half a dozen or so, and MAY even include weird ones like Gentoo. PRACTICALLY, we would certainly want to target three or four popular ones: MINT, UBUNTU, FEDORA, MANDRIVA, SUSE. NOTE: If we target DEBIAN, we JUST MIGHT get MINT and UBUNTU for free! SIMILARLY, if we target FEDORA, we probably get CENT OS and RED HAT for free (although RED HAT could probably be ignored, and CENT OS can probably be a good target too....) RANDOM THOUGHT: It would be nice to target NIX OS, but when I attempted to do so, I kept on running into weird memory errors that I couldn't overcome, due to a loss of patience. I'd like to get more familiar with NIX OS in general, though, because I want to have a better understanding of its package management system.

Virtual Machine Notes

I have chosen to use VirtualBox for testing images in other distributions, mostly because I ran into problems getting Qemu working (which philosophically I would prefer), but also because I have more experience with VirtualBox.

It's desirable to build this in a Virtual Machine, in order for AppImage to be able to run in older versions (in an attempt to maximize compatibility). I have done this in Debian Jessie (which is one less than the current version) by creating a VM with a shared folder between the VM and my host system. Symbolic links in shared folders are disabled by default, however, due to compatibility and security problems between Windows and Linux/Mac OS distributions, so compilation will only work if symbolic links are enabled.

Per an answer to an "Ask Ubuntu" question found here, this is done via:

VBoxManage setextradata <[VM_NAME]> VBoxInternal2/SharedFoldersEnableSymlinksCreate/<[SHARE_NAME]> 1

After running this command, it's necessary to restart the VirtualBox VM in question for the change to take effect.

Notes For Creating Electron Apps

It looks like Electron has several options for creating a standalon app file: manual creation, electron-packager, electron-builder, electron-forger. As far as I can determine, "electron-builder" is the most flexible of the three; in addition to being able to create Windows, OSX and Linux AppImage builds, it can create "deb", "rpm" and other Linux distribution formats.

Here are some links that seem important:

The electron-builder README introduction

An electron-builder tutorial

Electron Builder command line options

The settings for building the project are found in "package.json". The following settings are particularly important for building new things. (I really wish we could add comments to the "package.json" file, but unfortunately comments are NOT a part of the JSON standard, and thus would potentially be stripped out! :-( )

NOTE: It looks like the build system can also use an "electron-builder.yml" file, which allows comments. Perhaps we should use that. This may mean that some of the settings will be seperated from others (since we'll still need a "package.json").

• "scripts" -- not unique to "electron-rebuild", but used to identify scripts that is used by npm/yarn to run and/or build the application. Several options under scripts are of note:
  • "pack" -- if I understand correctly, this is used to create "test runs" for packaging. It's necessary to specify a directory where the files for this test run will be added.
  • "dist" -- creates a single file ideally ready for distribution.

  For both of these commands, the default target is the system the command is run on; if we want to sign for MacOS, it will be necessary to run this on MacOS; if we want to create something on Linux for Windows, apparently we need to have Wine (Wine Is Not an Emulator) installed.

  Apparently the options we'll want to use are:

  --mac, -m, -o --macos (for Mac OSX),
  --linux, -l (for Linux),
  --win, -w, --windows (for Windows),
  -lmw (for all three)

  NOTE: Since we use Chicken Scheme, which compiles binaries for a particular platform, it's likely that regardless of which system we wish to generate, we'll probably need to generate the files on the platforms we wish to target, rather than generate them all in one place -- unless we want to try to configure Chicken Scheme to cross-compile (which may very well lead to madness). Mac OS X in particular requires us to compile on Mac OS X if we want to digitally sign the package in question...

  If we want to create multiple types of packages (say, "AppImage" and "deb" for Linux) we can include target lists that specify what we want.

  If we wanted to do something weird, say "prebuild", this is probably

  where we would include the option.
• "build" -- this is used to store settings for different types of builds. The options that seem to be of greatest interest are:
• "dmg" -- build options for MacOS X (I'm still trying to figure out what "contents" means)
• "win" -- build options for Windows
• "linux" -- options for Linux
• "extraFiles" -- extra non-JS files that need to be included in the build; this is likely where we specify that we want to include files related to RhoLang and Ganache....

            Each entry has a "from" dir, a "to" dir, and a "filter"
            to determine what files should be included.  These can be
            included in each target type, so that we could include
            files especially for Windows, Linux, and MacOS, as well
            as generic files for all systems.
  
            Apparently symbolic links are copied as symbolic links,
            which is a bad idea.....
  

Apparently icon files, to be recognized by Electron Builder, need to be named "build/icon.icns", and it needs to be at most a 1024x1024-sized ICNS file. This can be converted readily enough from PNG files with the right tools.

By default Linux uses the icons that are designated for the Mac OS X target.

Once everything is set up correctly, we create the package via

yarn run dist

If everything goes "well" (where "well" means it somehow works, even if it produces a weird error that I haven't yet come to terms with), there will be a directory called "dist" which contains the file or files that we desire. Additionally, there's a sub-directory called "linux-unpacked" which apparently contains the files that go into the AppImage file.

When I rerun a build, I typically remove "dist" first, but it's unclear to me whether or not this is necessary. Sometimes I'll even remove node_modules and start completely from scratch.

Miscellaneous Notes

Binary Files

Binary files (such as "rholangCLI.jar") need to be kept in a "bin" folder, where AppImage can find them, and where Cryptofex IDE can find them when run from the command line. Specific information on setting up the necessary symlinks can be found in [electron-ide]/bin/BIN_README.md. (NOTE: The file system has changed quite a bit since Alpheus originally made notes about this; symlinks may no longer be needed....)

Binary files that are generated via our build process (such as via Chicken Scheme) are accessed through modules; thus, we don't need to include the results of such compilations in "bin" (unless we had a very good reason to keep the file completely 100% seperate from Cryptofex IDE).

Cryptofex IDE Directories

When Cryptofex IDE is first run, it creates two default directories in the home directory: ".cryptofex" to keep track of IDE settings (right now, only global settings, but at some point we'll want to add session settings here too) and "cryptofex-ide" to provide default files for an introduction to some of Cryptofex IDE's features.

AppImage expects these files to be found in "[electron-ide]/ide/intro-files"; thus, any changes to default files need to be made in this directory. Currently, Cryptofex IDE doesn't track changes to these files; thus, for changes in this directory to take effect, it is necessary to delete this directory, so that the IDE will see that it's missing, and fill in the directory with the current files. If there exists file named "cryptofex-ide", Cryptofex IDE defaults showing the home directory in the file browser.

(It just occurred to me that I have no idea why Cryptofex IDE seems to do the right thing when run from the command line, when it should likely have the same kinds of issues that it has with the "bin" directory; perhaps it doesn't, and I'm too tired at the moment to test to see if it does. I'm not 100% sure I care at the moment, either, since it's easy to populate this directory by running an AppImage of some sort.)

IDEA I have considered the possibility of checking the "cryptofex-ide" file to see if we could glean some information about directories, and then start Cryptofex IDE in the identified directory.

IDEA (A far better one, actually) Perhaps when a user starts Cryptofex IDE, we should pop up a window asking the user what directory they wish to start out with; we should default to "cryptofex-ide" if that directory exists, or "home" otherwise, but nonetheless let the user navigate to the correct directory.