docs about gradle and building the compiler, fix shell build script

build_the_compiler.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 
 echo "Compiling the parser..."
-java -jar ./parser/antlr/lib/antlr-4.7.2-complete.jar -o ./parser/src/prog8/parser -Xexact-output-dir -no-listener -no-visitor -package prog8.parser ./parser/antlr/prog8.g4
+java -jar ./parser/antlr/lib/antlr-4.7.2-complete.jar -o ./parser/src/prog8/parser -Xexact-output-dir -no-listener -no-visitor ./parser/antlr/prog8.g4
 
 
 PARSER_CLASSES=./out/production/parser

docs/source/building.rst

@@ -2,8 +2,33 @@
 Writing and building a program
 ==============================
 
-What is a "Program" anyway?
----------------------------
+First, getting a working compiler
+---------------------------------
+
+Before you can compile Prog8 programs, you'll have to build the compiler itself.
+First make sure you have installed the :ref:`requirements`.
+Then you can choose a few ways to create the compiler:
+
+**Using the shell script:**
+
+#. run the "build_the_compiler.sh" shell script
+#. it will create a "prog8compiler.jar" file which contains everything.
+#. run the compiler with "java -jar prog8compiler.jar" to see how you can use it.
+
+**using the Gradle build system:**
+
+#. run the command "./gradlew installDist"
+#. it will create the commands and required libraries in the "./compiler/build/install/p8compile/" directory
+#. run the compiler with the "./compiler/build/install/p8compile/bin/p8compile" command to see how you can use it.
+
+**download a precompiled version from github:**
+
+#. download a recent "prog8compiler.jar" from `the releases on Github <https://github.com/irmen/prog8/releases>`_
+#. run the compiler with "java -jar prog8compiler.jar" to see how you can use it.
+
+
+What is a Prog8 "Program" anyway?
+---------------------------------
 
 A "complete runnable program" is a compiled, assembled, and linked together single unit.
 It contains all of the program's code and data and has a certain file format that

docs/source/index.rst

@@ -130,11 +130,16 @@ of the `Vice emulator <http://vice-emu.sourceforge.net/>`_.
     packaged jar file.
 
 .. note::
-    To build the compiler from source, Kotlin SDK version 1.3 or newer is needed.
+    Building the compiler itself:
+
+    (re)building the compiler itself requires a Kotlin SDK version 1.3.
     The compiler is developed using the `IntelliJ IDEA <https://www.jetbrains.com/idea/>`_
     IDE from Jetbrains, with the Kotlin plugin (free community edition of this IDE is available).
     But a bare Kotlin SDK installation should work just as well.
-    A shell script is provided to build and package the compiler from the command line.
+    A shell script (``build_the_compiler.sh``) is provided to build and package the compiler from the command line.
+    You can also use the Gradle build system to build the compiler (it will take care of
+    downloading all required libraries for you) by typing ``gradle installDist`` for instance.
+    The output of this gradle build will appear in the "./compiler/build/install/p8compile/" directory.
 
 .. note::
     Development and testing is done on Linux, but the compiler should run on most

docs/source/todo.rst

@@ -29,11 +29,22 @@ Add more compiler optimizations to the existing ones.
 - on the language AST level
 - on the StackVM intermediate code level
 - on the final assembly source level
+- can the parameter passing to subroutines be optimized to avoid copying?
 
 
 Also some library routines and code patterns could perhaps be optimized further
 
 
+Eval stack redesign? (lot of work)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The eval stack is now a split lsb/msb stack using X as the stackpointer.
+Is it easier/faster to just use a single page unsplit stack?
+It could then even be moved into the zeropage to greatly reduce code size and slowness.
+
+Or just move the LSB portion into a slab of the zeropage.
+
+
 Misc
 ^^^^
 

prog8.iml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module external.linked.project.id="prog8" external.linked.project.path="$MODULE_DIR$" external.root.project.path="$MODULE_DIR$" external.system.id="GRADLE" external.system.module.group="" external.system.module.version="unspecified" type="JAVA_MODULE" version="4">
+  <component name="FacetManager">
+    <facet type="Python" name="Python">
+      <configuration sdkName="Python 3.7" />
+    </facet>
+  </component>
+  <component name="NewModuleRootManager" inherit-compiler-output="true">
+    <exclude-output />
+    <content url="file://$MODULE_DIR$">
+      <excludeFolder url="file://$MODULE_DIR$/.gradle" />
+      <excludeFolder url="file://$MODULE_DIR$/build" />
+    </content>
+    <orderEntry type="inheritedJdk" />
+    <orderEntry type="sourceFolder" forTests="false" />
+    <orderEntry type="library" name="Python 3.7 interpreter library" level="application" />
+  </component>
+</module>