some docs about the configurable targets, update kotlin to 2.1.10

.idea/libraries/KotlinJavaRuntime.xml

@@ -1,23 +1,23 @@
 <component name="libraryTable">
   <library name="KotlinJavaRuntime" type="repository">
-    <properties maven-id="org.jetbrains.kotlin:kotlin-stdlib-jdk8:2.1.0" />
+    <properties maven-id="org.jetbrains.kotlin:kotlin-stdlib-jdk8:2.1.10" />
     <CLASSES>
-      <root url="jar://$MAVEN_REPOSITORY$/org/jetbrains/kotlin/kotlin-stdlib-jdk8/2.1.0/kotlin-stdlib-jdk8-2.1.0.jar!/" />
-      <root url="jar://$MAVEN_REPOSITORY$/org/jetbrains/kotlin/kotlin-stdlib/2.1.0/kotlin-stdlib-2.1.0.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/jetbrains/kotlin/kotlin-stdlib-jdk8/2.1.10/kotlin-stdlib-jdk8-2.1.10.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/jetbrains/kotlin/kotlin-stdlib/2.1.10/kotlin-stdlib-2.1.10.jar!/" />
       <root url="jar://$MAVEN_REPOSITORY$/org/jetbrains/annotations/13.0/annotations-13.0.jar!/" />
-      <root url="jar://$MAVEN_REPOSITORY$/org/jetbrains/kotlin/kotlin-stdlib-jdk7/2.1.0/kotlin-stdlib-jdk7-2.1.0.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/jetbrains/kotlin/kotlin-stdlib-jdk7/2.1.10/kotlin-stdlib-jdk7-2.1.10.jar!/" />
     </CLASSES>
     <JAVADOC>
-      <root url="jar://$MAVEN_REPOSITORY$/org/jetbrains/kotlin/kotlin-stdlib-jdk8/2.1.0/kotlin-stdlib-jdk8-2.1.0-javadoc.jar!/" />
-      <root url="jar://$MAVEN_REPOSITORY$/org/jetbrains/kotlin/kotlin-stdlib/2.1.0/kotlin-stdlib-2.1.0-javadoc.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/jetbrains/kotlin/kotlin-stdlib-jdk8/2.1.10/kotlin-stdlib-jdk8-2.1.10-javadoc.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/jetbrains/kotlin/kotlin-stdlib/2.1.10/kotlin-stdlib-2.1.10-javadoc.jar!/" />
       <root url="jar://$MAVEN_REPOSITORY$/org/jetbrains/annotations/13.0/annotations-13.0-javadoc.jar!/" />
-      <root url="jar://$MAVEN_REPOSITORY$/org/jetbrains/kotlin/kotlin-stdlib-jdk7/2.1.0/kotlin-stdlib-jdk7-2.1.0-javadoc.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/jetbrains/kotlin/kotlin-stdlib-jdk7/2.1.10/kotlin-stdlib-jdk7-2.1.10-javadoc.jar!/" />
     </JAVADOC>
     <SOURCES>
-      <root url="jar://$MAVEN_REPOSITORY$/org/jetbrains/kotlin/kotlin-stdlib-jdk8/2.1.0/kotlin-stdlib-jdk8-2.1.0-sources.jar!/" />
-      <root url="jar://$MAVEN_REPOSITORY$/org/jetbrains/kotlin/kotlin-stdlib/2.1.0/kotlin-stdlib-2.1.0-sources.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/jetbrains/kotlin/kotlin-stdlib-jdk8/2.1.10/kotlin-stdlib-jdk8-2.1.10-sources.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/jetbrains/kotlin/kotlin-stdlib/2.1.10/kotlin-stdlib-2.1.10-sources.jar!/" />
       <root url="jar://$MAVEN_REPOSITORY$/org/jetbrains/annotations/13.0/annotations-13.0-sources.jar!/" />
-      <root url="jar://$MAVEN_REPOSITORY$/org/jetbrains/kotlin/kotlin-stdlib-jdk7/2.1.0/kotlin-stdlib-jdk7-2.1.0-sources.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/jetbrains/kotlin/kotlin-stdlib-jdk7/2.1.10/kotlin-stdlib-jdk7-2.1.10-sources.jar!/" />
     </SOURCES>
   </library>
 </component>

build.gradle.kts

@@ -3,7 +3,7 @@ import org.jetbrains.kotlin.gradle.internal.config.LanguageFeature
 
 
 plugins {
-    kotlin("jvm") version "2.1.0"
+    kotlin("jvm") version "2.1.10"
 }
 
 allprojects {

docs/source/compiling.rst

@@ -232,6 +232,9 @@ One or more .p8 module files
     Sets the target output of the compiler. This option is required.
     ``c64`` = Commodore 64, ``c128`` = Commodore 128, ``cx16`` = Commander X16, ``pet32`` - Commodore PET model 4032,
     ``atari`` = Atari 800 XL, ``neo`` = Neo6502, ``virtual`` = builtin virtual machine.
+    You can also specify a file name as target, prog8 will when try to read the target
+    machine's configuration and properties from that configuration file instead of using one of the built-in targets.
+    See :ref:`customizable_target` for details about this.
 
 ``-varsgolden``
     Like ``-varshigh``, but places the variables in the $0400-$07FF "golden ram" area instead.

docs/source/index.rst

@@ -20,7 +20,7 @@ They targeted CPUs are the `6502 <https://en.wikipedia.org/wiki/MOS_Technology_6
 They are from the late 1970's and early 1980's and was used in many home computers from that era,
 such as the `Commodore 64 <https://en.wikipedia.org/wiki/Commodore_64>`_.
 
-You can compile programs for various machines:
+You can compile programs for various machines that are built in into the compiler:
 
 * Commander X16  (with 65c02 cpu, 65816 cpu specifics are currently not supported by prog8 itself)
 * Commodore 64
@@ -28,6 +28,7 @@ You can compile programs for various machines:
 * Commodore PET (limited support)
 * Atari 800 XL (very limited support)
 * Neo6502 (very imited support)
+* any other 65(C)02 target machine or setup can be configured to a great extent in a user written configuration file.
 
 Some language features are mentioned below, and you can also read :ref:`comparingprog8` if you
 want to quickly read about how Prog8 compares to well-known other languages.

docs/source/targetsystem.rst

@@ -26,6 +26,32 @@ This chapter explains some relevant system details of the c64 and cx16 machines.
     it is often possible to compile the *exact same program* for
     different machines (just change the compilation target flag)!
 
+.. note::
+    When you specify a file name as target, prog8 will try to read the target
+    machine's configuration and properties from that configuration file instead.
+    See :ref:`customizable_target` for details about this.
+
+
+.. _customizable_target:
+
+Customizable targets
+====================
+
+You can also specify a file name instead of one of the built in target machine names, when using the ``-target`` option.
+In this case the compiler will not use one of the builtin machines configurations, but read it from the configuration file.
+This allows you to define and change your own target machine configuration, and maybe allow Prog8 to generate
+programs for new machines or existing ones it doesn't yet know about.
+
+The configuration file should be a "targetname.properties" file, which is basically a text file containing "key=value" lines.
+The "targetname" filename base part will be taken as the name of the configured compilation target.
+The contents of the file is pretty extensive and it's easier to just look at some examples that are already included:
+`target configuration examples <https://github.com/irmen/prog8/tree/master/examples/customtarget/>`_ .
+
+Most of the things discussed in the :ref:`portingguide` can and must be configured properly in the target configuration file.
+You also need to create some essential ``syslib`` library module for the configured target, because the Prog8
+compiler won't have a built in library that can be used this time. The customtarget examples also show how to build
+the essentials.
+
 
 Memory Model
 ============

docs/source/todo.rst

@@ -2,6 +2,7 @@ TODO
 ====
 
 - Make some of the target machine config externally configurable (for 1 new target, the existing ones should stay as they are for the time being)
+- Should there be some form of "CUSTOM" launchertype where the startup assembly code can also be configured in the target.properties?
 
 - add paypal donation button as well?
 - announce prog8 on the 6502.org site?