mention main block size restriction

docs/source/_static/symboldumps/skeletons-c128.txt

@@ -1,5 +1,5 @@
 
-Prog8 compiler v12.0.1 by Irmen de Jong (irmen@razorvine.net)
+Prog8 compiler v12.0.2 by Irmen de Jong (irmen@razorvine.net)
 This software is licensed under the GNU GPL 3.0, see https://www.gnu.org/licenses/gpl.html
 
 Compiling program import-all-c128.p8
@@ -574,6 +574,8 @@ c128  {
     SWAPPER  ()  clobbers (A,X,Y)  = $ff5f
     banks  (ubyte banks @A) 
     disable_basic  ()  clobbers (A) 
+    disable_fkey_macros  () 
+    enable_fkey_macros  () 
     getbanks  () -> ubyte @A 
     x16jsrfar  () 
 }

docs/source/_static/symboldumps/skeletons-c64.txt

@@ -1,5 +1,5 @@
 
-Prog8 compiler v12.0.1 by Irmen de Jong (irmen@razorvine.net)
+Prog8 compiler v12.0.2 by Irmen de Jong (irmen@razorvine.net)
 This software is licensed under the GNU GPL 3.0, see https://www.gnu.org/licenses/gpl.html
 
 Compiling program import-all-c64.p8

docs/source/_static/symboldumps/skeletons-cx16.txt

@@ -1,5 +1,5 @@
 
-Prog8 compiler v12.0.1 by Irmen de Jong (irmen@razorvine.net)
+Prog8 compiler v12.0.2 by Irmen de Jong (irmen@razorvine.net)
 This software is licensed under the GNU GPL 3.0, see https://www.gnu.org/licenses/gpl.html
 
 Compiling program import-all-cx16.p8

docs/source/_static/symboldumps/skeletons-pet32.txt

@@ -1,5 +1,5 @@
 
-Prog8 compiler v12.0.1 by Irmen de Jong (irmen@razorvine.net)
+Prog8 compiler v12.0.2 by Irmen de Jong (irmen@razorvine.net)
 This software is licensed under the GNU GPL 3.0, see https://www.gnu.org/licenses/gpl.html
 
 Compiling program import-all-pet32.p8
@@ -534,6 +534,7 @@ txt  {
     color  (ubyte txtcol) 
     fill_screen  (ubyte character @A, ubyte color @Y)  clobbers (A) 
     getchr  (ubyte col @A, ubyte row @Y)  clobbers (Y) -> ubyte @A 
+    getclr  (ubyte col @A, ubyte row @Y) -> ubyte @A 
     height  ()  clobbers (X,Y) -> ubyte @A 
     home  () 
     input_chars  (^^ubyte buffer @AY)  clobbers (A) -> ubyte @Y 
@@ -562,7 +563,7 @@ txt  {
     scroll_left  ()  clobbers (A,X,Y) 
     scroll_right  ()  clobbers (A,X) 
     scroll_up  ()  clobbers (A,X) 
-    setcc  (ubyte col, ubyte row, ubyte character, ubyte charcolor) 
+    setcc  (ubyte col @X, ubyte row @Y, ubyte character @A, ubyte charcolor @R0) 
     setchr  (ubyte col @X, ubyte row @Y, ubyte character @A)  clobbers (A,Y) 
     setclr  (ubyte col, ubyte row, ubyte color) 
     size  ()  clobbers (A) -> ubyte @X, ubyte @Y 

docs/source/_static/symboldumps/skeletons-virtual.txt

@@ -1,5 +1,5 @@
 
-Prog8 compiler v12.0.1 by Irmen de Jong (irmen@razorvine.net)
+Prog8 compiler v12.0.2 by Irmen de Jong (irmen@razorvine.net)
 This software is licensed under the GNU GPL 3.0, see https://www.gnu.org/licenses/gpl.html
 
 Compiling program import-all-virtual.p8

docs/source/compiling.rst

@@ -405,6 +405,21 @@ Avoid using 'a', 'x' or 'y' as symbols in your inlined assembly code.
 Also avoid using 64tass' built-in function or type names as symbols in your inlined assembly code.
 The 64tass manual contains `a list of those <https://tass64.sourceforge.net/#functions>`_.
 
+Program loads but crashes immediately on startup
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Assuming there are no programming errors in the code and the compiler has no code generation bugs, there can be various factors that cause this:
+
+#. you are using ``%option no_sysinit`` but the program might depend on proper initialization of the system before it can run.
+   Try removing this directive to see if it helps.
+#. the ``main`` block is too large for default system RAM, causing the vital program startup routines that Prog8 requires
+   to move outside of the default RAM area, making them inaccessible. For example on the C128 this can occur quite quickly
+   because in the default memory configuration, the BASIC ROM already appears at $4000, leaving *very* little space for your
+   program code by default. Prog8 attempts to reconfigure the memory but it can't because the routine doing that is not
+   accessible anymore and the program will jump to random code, crashing the system.
+   Make sure the startup logic appears "soon enough" in your program - if in doubt, check the generated assembly file listing
+   to see how large the ``main`` block is and where the startup routines are placed. If this is in fact the problem,
+   you need to modularize the code and move stuff out of the ``main`` block and into their own block(s).
+
 
 Examples
 --------

docs/source/programming.rst

@@ -217,10 +217,13 @@ As any subroutine, it has to end with a ``return`` statement (or a ``goto`` call
     }
 
 
-The ``main`` module is always relocated to the start of your programs
+The ``main`` block is always relocated to the start of your programs
 address space, and the ``start`` subroutine (the entrypoint) will be on the
 first address. This will also be the address that the BASIC loader program (if generated)
-calls with the SYS statement.
+calls with the SYS statement. **It is advised to not put too much code and data into the main block**,
+because that may cause Prog8's vital program initialization routines to be placed outside of normal accessible program RAM,
+causing an immediate program crash on startup. If this happens you need to modularize the code and move
+stuff into their own block(s).
 
 
 .. _directives: