Split up editor docs

skip-ci

Author: britzl

README_BUILD.md

@@ -40,15 +40,19 @@ The following platforms are supported:
 
 Start by setting up the build environment:
 
-    $ ./scripts/build.py shell
+```sh
+$ ./scripts/build.py shell
+```
 
 This will start a new shell with all of the required environment variables set (`DYNAMO_HOME` etc).
 
 ### STEP 2 - Install packages and SDKs
 
 Next thing you need to do is to install external packages and download required platform SDKs:
 
-    $ ./scripts/build.py install_ext --platform=... --package-path=...
+```sh
+$ ./scripts/build.py install_ext --platform=... --package-path=...
+```
 
 It is important that you provide the `--platform` option to let the `install_ext` command know which platform you intend to build for (the target platform). When the `install_ext` command has finished you will find the external packages and downloaded SDKs in `./tmp/dynamo_home/ext`.
 
@@ -69,11 +73,15 @@ Due to licensing restrictions the SDKs are not distributed with Defold. You need
 
 With the setup and installation done you're ready to build the engine:
 
-    $ ./scripts/build.py build_engine --platform=...
+```sh
+$ ./scripts/build.py build_engine --platform=...
+```
 
 This will build the engine and run all unit tests. In order to speed up the process you can skip running the tests:
 
-    $ ./scripts/build.py build_engine --platform=... --skip-tests -- --skip-build-tests
+```sh
+$ ./scripts/build.py build_engine --platform=... --skip-tests -- --skip-build-tests
+```
 
 Anything after `--` is passed directly as arguments to Waf. The built engine ends up in `./tmp/dynamo_home/bin/%platform%`.
 
@@ -83,20 +91,26 @@ Anything after `--` is passed directly as arguments to Waf. The built engine end
 
 When you are working on a specific part of the engine there is no need to rebuild the whole thing to test your changes. You can use Waf directly to build and test your changes (see Unit tests below for more information about running tests):
 
-    $ cd engine/dlib
-    $ waf
+```sh
+$ cd engine/dlib
+$ waf
+```
 
 You can also use rebuild a specific part of the engine and create a new executable:
 
-    # Rebuild dlib and sound modules and create a new executable
-    $ ./scripts/submodule.sh x86_64-darwin dlib sound
+```sh
+# Rebuild dlib and sound modules and create a new executable
+$ ./scripts/submodule.sh x86_64-darwin dlib sound
+```
 
 ---
 
 ## Unit tests
 
 Unit tests are run automatically when invoking waf if not `--skip-tests` is specified. A typically workflow when working on a single test is to run:
 
-    $ waf --skip-tests && ./build/default/.../test_xxx
+```sh
+$ waf --skip-tests && ./build/default/.../test_xxx
+```
 
 With the flag `--test-filter=` it's possible to run a single test in the suite, see [jctest documentation](https://jcash.github.io/jctest/api/03-runtime/#command-line-options)

README_ENGINE.md

@@ -4,6 +4,10 @@
 
 The engine source code can be found in the `/engine` folder. The source code is divided into a number of different modules/folders:
 
+### Build process
+
+[Build instructions for the engine are here](/README_BUILD.md).
+
 ### Engine libraries
 
 To see the actual, ordered, list of engine libraries, look for `ENGINE_LIBS` in [./scripts/build.py](./scripts/build.py), and also add `dlib`, and `texc` to that list.

README_SETUP.md

@@ -2,6 +2,6 @@
 
 (Setup instructions for the editor [here](/editor/README.md)).
 
-* macOS - [Setup instructions](/README_SETUP_MACOS.md)
-* Windows - [Setup instructions](/README_SETUP_WINDOWS.md)
-* Linux - [Setup instructions](/README_SETUP_LINUX.md)
+* macOS - [Setup instructions](README_SETUP_MACOS.md)
+* Windows - [Setup instructions](README_SETUP_WINDOWS.md)
+* Linux - [Setup instructions](README_SETUP_LINUX.md)

editor/README.md

@@ -1,200 +1,22 @@
 # Defold Editor
 
-## Requirements
-* [Java 11](https://jdk.java.net/11/) ([installation instructions](#installing-jdk11) - Note that we do not yet officially support development with a newer version of Java than 11.
-* Leiningen ([install instructions](#install-leiningen))
+## Overview
+Editor overview [here](README_SYSTEMS_OVERVIEW.md).
 
-## Installing JDK 11
-### macOS
-
-* Download the [macOS](https://download.java.net/java/GA/jdk11/9/GPL/openjdk-11.0.2_osx-x64_bin.tar.gz) version and extract it
-* Run `sudo cp -R <path-to-extracted-folder>/jdk-11.0.2.jdk /Library/Java/JavaVirtualMachines/`
-* Verify that the jdk version is available by running `/usr/libexec/java_home -V`
-* Switch to the new version by running `/usr/libexec/java_home -v 11.0.2`
-
-### Linux
-
-* Download [Linux](https://download.java.net/java/GA/jdk11/9/GPL/openjdk-11.0.2_linux-x64_bin.tar.gz) version and extract it somewhere
-* Run `sudo update-alternatives --install "/usr/bin/java" "java" "/path/to/jdk/bin/java" 1102`
-* Run `sudo update-alternatives --install "/usr/bin/javac" "javac" "/path/to/jdk/bin/javac" 1102`
-* If require, switch to new version using `sudo update-alternatives --config java` and `sudo update-alternatives --config javac`
-
-### Notes
-
-If you are using IntelliJ for lein tasks, you will need to first add the new SDK (file->project structure/SDKs)
-and then set the project SDK setting (file->project structure/Project) to the new version.
-
-## Installing Leiningen
-### Windows
-
-First of all, follow the Windows instructions in [Defold Readme](../README.md)
-
-* Start `msys.bat` as described
-* Download the [lein.sh script](https://raw.githubusercontent.com/technomancy/leiningen/stable/bin/lein) from [Leiningen.org](http://leiningen.org) Put it somewhere in your (msys) path - if you're lazy, put it in `C:\MinGW\msys\1.0\bin`. You might need to `chmod a+x lein.sh`.
-* Run `lein` in the `editor` subdirectory
-  This will attempt to download leiningen and dependencies to your home directory.
-
-  - If this fails with message
-
-          Could not find or load main class clojure.main
-
-    Try pointing your `HOME` environment variable to your “windows home”. For instance change it from `/home/Erik.Angelin` (msys) to `/c/Users/erik.angelin`:
-
-        export HOME="/c/Users/erik.angelin"
-
-    The problem seems to be that the (windows) java class path points to an invalid home directory.
-
-  - If this fails because the github certificate cannot be verified:
-
-          export HTTP_CLIENT='wget --no-check-certificate -O'
-
-### macOS/Linux
-
-* Install Leiningen `brew install leiningen`
 
 ## Setup
-* Open a terminal/console and change directory to `defold`.
-
-    `cd defold`
-
-* Setup the shell environment (consider putting it in an alias in your bash profile):
-
-    `./scripts/build.py shell --platform=...`
-
-* Run install_ext for the correct platform:
-
-    `./scripts/build.py install_ext --platform=...`
-
-* Build the engine:
-
-    `./scripts/build.py build_engine --platform=... --skip-tests -- --skip-build-tests`
-
-* Build builtins:
-
-    `scripts/build.py build_builtins`
-    
-* Build reference documentation:
-
-    `scripts/build.py build_docs`
-
-* Build Bob:
-
-    `scripts/build.py build_bob --skip-tests`
-
-* Change directory to the editor directory
-
-    `cd editor`
-
-* Run:
-
-    `lein init`
+(Setup instructions for the engine [here](../README_SETUP.md)).
 
-## Cursive IDE Setup
-Some of the remaining instructions are about EMACS. If instead you want to use the Cursive IDE, read the [Cursive setup guide](README_CURSIVE.md).
+* macOS - [Setup instructions](README_SETUP_MACOS.md)
+* Windows - [Setup instructions](README_SETUP_WINDOWS.md)
+* Linux - [Setup instructions](README_SETUP_LINUX.md)
 
-## Running Tests
-`lein test` will run all the tests including the integration tests.
+If you want to use the Cursive IDE, read the [Cursive setup guide](README_CURSIVE.md).
 
-If you are using a repl, you can also run the tests by calling `(suite/suite)`.
 
-## Setup NREPL for debugging
+## Build and debug/REPL
+Build and debug/REPL instructions [here](README_BUILD.md).
 
-If you want to work on the editor chances are you want to `connect` or `jack-in` to a REPL as described below.
-
-For this to work you will need a `~/.lein/profiles.clj` file and put the nREPL, Cider (etc) dependencies there;
-
-```
-{:user {:plugins [[cider/cider-nrepl "0.10.2"]
-                  [refactor-nrepl "1.1.0" :exclusions [org.clojure/clojure]]]
-        :dependencies [[org.clojure/tools.nrepl "0.2.12"]]}}
-```
-
-Please note that Lein will introduce a nREPL dependency automagically, but its a good idea to override to your preferred version here anyway.
-
-## Running the Editor
-`lein run` will launch the editor as well as providing a nrepl port
-for you to jack into
-
-## Building the Editor
-
-Use `scripts/bundle.py` to produce a bundled version of the editor.
-
-There are a few different scenarios in which you might want to build the editor locally:
-
-- Local editor sources, archived engine artifacts based on HEAD:
-  - `./scripts/bundle.py --platform=x86_64-win32 --version=1.2.3.4 --engine-artifacts=archived`
-    - This will fetch engine and launcher artifacts using the `HEAD` revision.
-- Local editor sources, archived engine artifacts based on a different revision:
-  - `./scripts/bundle.py --platform=x86_64-win32 --version=1.2.3.4 --engine-artifacts=archived-stable`
-    - This will fetch engine and launcher artifacts using the latest stable revision and is handy if you are on a branch where no engine artifacts have been archived.
-- Local editor sources, local engine artifacts, local launcher:
-  - `./scripts/bundle.py --platform=x86_64-win32 --version=1.2.3.4 --engine-artifacts=dynamo-home`
-    - This will use local engine artifacts from `$DYNAMO_HOME`, with the exception of the launcher.
-- Local editor sources, archived engine artifacts, local launcher:
-  - `./scripts/bundle.py --platform=x86_64-win32 --version=1.2.3.4  --engine-artifacts=archived --launcher ../tmp/dynamo_home/bin/x86_64-darwin/launcher`
-    - This will fetch engine artifacts using the `HEAD` revision.
-
-
-## Jacking into a REPL
-
-You can also use `M-x cider-jack-in` or launch the editor inside Cursive for debugging with breakpoints etc.
-
-First set the environment variable `DYNAMO_HOME`. Example of a value `/Users/martin/work/defold/tmp/dynamo_home`.
-
-After you jacked in do the following to load and start the app;
-
-```
-user=> (dev)
-dev=> (go)
-```
-
-## Running Benchmarks
-`lein benchmark` will run the benchmarks and put the results to the
-`test/benchmark/bench-result.txt` file. Make sure to have everything
-on your system closed down
-
-## Generating the docs
-Running `lein doc` will generate the codox to the target/docs directory
 
 ## Styling
-A single stylesheet is set on the root node (by convention) in the scene. The stylesheet `editor.css` is loaded as a regular java resource, from the uberjar or from the file-system in dev-mode. If an `editor.css` is found in the current working directory that file will take precedence over the aforementioned java resource.
-
-The stylesheet can be reloaded with the function key `F5`.
-
-The `editor.css` stylesheet is generated from the the sass/scss files in `styling/stylesheets`. To generate the file you can use either leiningen or gulp:
-
-**leiningen**
-
-- `lein sass once` to generate once
-- `lein sass watch` to watch and re-generate css on changes
-
-**nodejs**
-
-In the `styling` directory:
-- `npm install`
-
-- `gulp` to generate once
-- `gulp watch` to watch and re-generate css on changes
-
-See `styling/README.md` for details.
-
-
-### JavaFX Styling
-
-The best way to understand how JavaFX styling works is by studying the default stylesheet `modena.css` included in `jfxrt.jar`
-
-## Bundling games and running in browser
-
-As a temporary solution, we use Bob (from Editor1) as the content pipeline for bundling and running in the browser. In order to setup Bob locally, you need to:
-
-- Build the engine for the specific platform, e.g. `python scripts/build.py build_engine --platform=js-web --skip-tests -- --skip-build-tests`
-  - For android, you also need to `build_go` through `build.py` to obtain `apkc`
-- Build Bob with local artifacts, `python scripts/build.py build_bob`
-- `lein init`, which will install `bob.jar` as a local maven package
-
-## Using a local bob.jar
-
-When developing it can be convenient to use a local bob.jar instead of the one bundled with the editor. This can by adding `,-Ddefold.dev=true` to the end of the `vmargs =` field of the editor config.
-
-* On macOS the config is inside the application file: `Defold.app/Contents/Resources/config`
-* On Windows and Linux the config file is located next to the Defold executable.
+Editor styling documentation [here](README_STYLING.md).