Developer Guide

Getting started, branches, packaging

Getting Started

  1. Follow instructions to install yarn(which tell you to install Node as well).
  2. Download and install the latest (2.x) Dotnet Core SDK
    For Mac users, download and install Mono from official website (the version from brew is incomplete, may lead to MSB error on step 7).
  3. Download & unzip the Visual2 repo, or if contributing clone it locally, or fork it on github and then clone it locally.
  4. Navigate to the project root directory (which contains this README) in a command-line interpreter. For Windows usage make sure if possible for convenience that you have a _tabbed_ command-line interpreter that can be started direct from file explorer within a specific directory (by right-clicking on the explorer directory view). That makes things a lot more pleasant. I recommend Hyper, for example, runs multiple tabs and will split window between two tabs, great for running start and launch scripts concurrently in a single window. Beware that under Windows Hyper uses ctrl-shift-C, ctrl-shift-V for copy and paste.
  5. Fetch the required npm packages by executing yarn install. This project consistently uses yarn Node package manager instead of npm.
  6. On macOS or linux ensure you have paket installed. Run setup.bat (on Windows) or sh setup.sh (on linux or macOS). This downloads and updates the submodules, and installs their packages individually (necessary because of the submodule structure), then restores the global packages. On other systems run the statements in this file (modified if needed for your system) individually. If MSB error occur while running the script (on macOS) and you were using Mono installed by brew previously, run brew uninstall mono and refer to step 2 for install Mono correctly).
  7. Goto step 10 if all you want to do is to generate uptodate binaries.
  8. In a terminal window (for example under hyper) compile fsharp code to javascript using webpack by executing yarn start (shortcut for yarn run start). This runs the start script defined in package.json. The start script compiles everything once and then watches source files recompiling whenever any change, so it is normal run continuously throughout development. You will need to view the yarn start output throughout development since if compile fails the output makes this clear via red-colored text. Although Ionide will also provide error messages on code that does not compile it is possible to miss these when making quick changes.
  9. Open your electron app in a new terminal tab by running yarn launch. This command will start the application and also _hot reload_ it whenever source files are recompiled, or CSS files changed. Therefore it normally also runs continuously through development. The total time from saving an updated F# source file to reload is typically 5s. Make sure you have this development environment working effectively for you: an HD screen without scaling is helpful because it allows your editor, the Visual2 app, and the command windows all to be visible simultaneously.
  10. Run yarn pack-win, yarn pack-linux, yarn pack-osx at any time to create a set of system-specific self-contained binaries in ./dist/os-name/* and a zip in ./dist. Each binary distribution consists of a portable directory with all dependencies, so use the appropriate one of these if you just want to run Visual2 is to double click and do not need to develop code. For osx, the easiest way to run Visual2 once it has been built is to navigate to ./dist/VisUAL2-darwin-x64 and execute open -a VisUAL2.app in terminal. Note that some host-target combinations will not correctly generate: pack-osx must be executed on os-x.
  11. To see console debug printout etc from the running Visual2 app press Ctrl-Shift-I to toggle electron dev tools on and note that any F# printout and errors will be displayed under the console tab.

Branches

  1. master: Modified VisUAL2 with MVU implemented
  2. original: VisUAL2 without the MVU pattern
  3. elmish-bare-monaco-editor: bare skeleton with monaco editor
  4. elmish-bare-react-monaco-editor: bare skeleton with react monaco editor

Packaging VisUAL2 as binaries

After you have compiled code (and checked it works) yarn pack-all will run electron packager and generate ./dist/os-name/* files. See also run-packager-all.bat if using windows host to make macOS binary. See the packaging issue for more details of how this has been customised to work. Note that if this breaks you can still run individual targets as below.

Useful shortcuts for specific common target OS:

  • yarn pack-osx (macOS - but see below if running from windows host)
  • yarn pack-win (windows)
  • yarn pack-linux (linux)
    • Note on macOS binaries. These cannot be packaged as DMG (and therefore used) except on a macOS host. On macOS you need to run yarn make-osx-dmg which will FIRST run yarn pack-osx and then generate the macOS DMG file as ./dist/visual2-osx.dmg.

    Boilerplate Development

    At some point you may want to change the boilerplate that glues this project together. Understanding all of the boilerplate is not normally needed, and takes some time, but it is possible since each part is quite simple and documented:

    There are five distinct sources for this:

    • ./app/js/monaco-init.js. This is setup code for Monaco editor and explained in the Monaco documentation.
    • *.fsproj. These are the dotnet core project files for F# which should be changed to add F# dependencies or source files. They are simple and well documented in any of the F# Getting Started guides. Also, they can be changed in a GUI by both VS code / Ionide, and Visual Studio. The Ionide GUI change may not work as of May 2018 (try it).
    • ./package.json. This is instructions to Yarn and FABLE (v1.x) to compile the F# source to JS with Node JS dependencies. Well documented by fable-compiler.
    • ./webpack.config Instructions to webpack to bundle the JS files generated by FABLE. Well documented by webpack, but note the need to copy files caused by the non-standard Monaco loader.
    • setup.bat or setup.sh. Code to bootstrap and get initial binary dependencies for F# projects dotnet.

    Other top-level files (never changed manually):

    • yarn.lock auto-generated by yarn contains the package versions currently used of all node packages. These can get upgraded by yarn upgrade. Upgrading to latest versions is normally but not always trouble-free.
    • paket.lock, paket.dependencies. Files used by Paket to track nuget (.Net) packages. This project has only development-time .Net dependencies and these do not need to be upgraded.
    • Nuget.Config. Used by NuGet. You can view the project under Visual Studio and change packages in a GUI via NuGet but this is not recommended.
    • ARM.Monaco.Editor.sln. this solution file allows all three F# projects to be integrated by Visual Studio or Ionode. It is useful for editing code, but compiling is done via FABLE which uses information from *.fsproj files and ignores the *.sln file.
    Maintained by scc416