* submodule instructions

README.md

@@ -4,17 +4,17 @@ Pas2js is an open source Pascal to JavaScript transpiler.
 It parses Object Pascal and emits JavaScript.
 
 Official site:
-http://wiki.freepascal.org/pas2js
+[http://wiki.freepascal.org/pas2js](http://wiki.freepascal.org/pas2js)
 
 
 ## Directories
 
-packages - source files needed to compile pas2js programs
-demo - examples
-bin - output folder for binaries, e.g. pas2js.exe
-compiler - source files to compile the compiler. This is an external submodule link.
-units - output folder of compiler ppu/o files
-utils - utilities
+* **packages** - source files needed to compile pas2js programs
+* **demo** - examples
+* **bin** - output folder for binaries, e.g. pas2js.exe
+* **compiler** - source files to compile the compiler. This is an external submodule link.
+* **units** - output folder of compiler ppu/o files
+* **utils** - utilities
 
 ## Building
 
@@ -34,7 +34,35 @@ as well if it has the latest version.
 
 ### building pas2js
 
-#### Under Linux/macOS 
+### Complete checkout
+
+The makefile expects the sources of FPC to be present under the `compiler` directory.
+You can copy these sources there, or make a symlink to the sources.
+
+The git repository contains a submodule link to the FPC sources.
+You can use this to have an automatically correct version of fpc
+
+When you do a `git clone`, make sure you also specify the `--recurse-submodules`  option:
+```sh
+git clone --recurse-submodules https://gitlab.com/freepascal.org/fpc/pas2js.git
+```
+If you didn't do this, issue the init and update commands:
+```sh
+git submodule init
+```
+and update:
+```sh
+git submodule update
+```
+This will have the same effect as when you do a --recurse-submodules.
+
+After doing a git pull, you must also update the submodule:
+```sh
+git submodule update --init --recursive
+```
+This will pull any upstream changes to the FPC repository.
+
+#### Under Linux/macOS
 type the following command:
 ```sh
 make all
@@ -44,7 +72,7 @@ This creates with a 64-bit fpc the executable `bin/x86_64-linux/pas2js`
 and a basic config file `bin/x86_64-linux/pas2js.cfg`.
 
 
-#### Under Windows 
+#### Under Windows
 
 
 Make sure that you use the `make.exe` from fpc, not the one from Delphi by setting the
@@ -76,4 +104,4 @@ containing those parameters.
 
 [http://wiki.freepascal.org/pas2js.cfg]([http://wiki.freepascal.org/pas2js.cfg])
 
-
+