diff --git a/.agent/workflows/startup.md b/.agent/workflows/startup.md
index 8bcc55f0e..e088a3bc6 100644
--- a/.agent/workflows/startup.md
+++ b/.agent/workflows/startup.md
@@ -2,4 +2,4 @@
description: Startup workflow to load project context
---
-1. Read the file `QWEN.md` in the project root to understand the project structure, module descriptions, and development commands.
+1. Read the file `AGENTS.md` in the project root as initial system prompt to build context and instructions about the project structure, module descriptions, and development commands.
diff --git a/.idea/kotlinc.xml b/.idea/kotlinc.xml
index 853cecc12..d109dbf65 100644
--- a/.idea/kotlinc.xml
+++ b/.idea/kotlinc.xml
@@ -7,13 +7,13 @@
-
-
+
+
-
+
\ No newline at end of file
diff --git a/.idea/libraries/KotlinJavaRuntime.xml b/.idea/libraries/KotlinJavaRuntime.xml
index 5e7d961f9..3e4aa46df 100644
--- a/.idea/libraries/KotlinJavaRuntime.xml
+++ b/.idea/libraries/KotlinJavaRuntime.xml
@@ -1,23 +1,23 @@
-
+
-
-
+
+
-
+
-
-
+
+
-
+
-
-
+
+
-
+
\ No newline at end of file
diff --git a/.idea/libraries/eclipse_lsp4j.xml b/.idea/libraries/eclipse_lsp4j.xml
index ea32d9e69..2b026f2d7 100644
--- a/.idea/libraries/eclipse_lsp4j.xml
+++ b/.idea/libraries/eclipse_lsp4j.xml
@@ -1,11 +1,11 @@
-
+
-
-
-
-
+
+
+
+
diff --git a/.qwen/settings.json b/.qwen/settings.json
new file mode 100644
index 000000000..de37917d1
--- /dev/null
+++ b/.qwen/settings.json
@@ -0,0 +1,6 @@
+{
+ "context": {
+ "fileName": "AGENTS.md"
+ },
+ "$version": 3
+}
\ No newline at end of file
diff --git a/AGENTS.md b/AGENTS.md
index a6ccdb710..ec6b17dcf 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,32 +1,97 @@
-# Agent Instructions for Prog8 Project
+# Agents.md
-## Required Startup Actions
+Context and instructions for AI Agents to work on this project.
-When starting a new session with this project, you **MUST** perform these actions before proceeding with any user requests:
+## Project Overview
+- This project is a compiler for the Prog8 programming language.
+- Prog8 is a programming language primarily targeting 8-bit retro systems with the 6502 CPU, such as the Commodore 64, Commodore 128, and Commander X16.
+- The compiler has a 6502 code generator backend, and an IR code generator.
+- The IR code is meant to be used in a new machine specific code generator backend (primarily 6502 but maybe 68000 as well later)
+- The compiler includes a simple 'virtual machine' that can execute the IR code directly via interpretation.
+- Prog8 source files have .p8 extension
+- Prog8 source files are a "module" that can contain 1 ore more "blocks". They can also import other modules, from internal library files or from source files on the filesystem.
+- The prog8 compiler is written mostly in Kotlin, those files have the .kt extension.
-1. **Read QWEN.md** - Execute: `read /home/irmen/Projects/prog8/QWEN.md`
- - This file contains critical project context including:
- - Project overview (Prog8 compiler for 8-bit retro systems)
- - Module descriptions for all 20+ modules
- - Gradle commands and build instructions
- - Prog8 compiler usage examples
- - Development shortcuts
+## Prog8 language feature hints
+- an overview of the language features can be found in the documentation file docs/source/introduction.rst
+- the syntax and grammar is specified in an ANTLR4 grammar file found in the parser directory
+- available primitive datatypes are bool, byte, ubyte, word, uword, long and float. ubyte and uword are unsigned the others are signed. The long type is 4 bytes and the float type is 5-byte "Microsoft" floating point.
+- there is a str type which is a 0-terminated string consisting of ubytes
+- there are also arrays, and pointers. Pointer notation differs from C.
+- there are also structs which can contain primitive types. Prog8 does not yet have by-value struct variables, only pointer to structs.
+- while there are larger than byte datatypes, the intended compiler target is a 6502 CPU system which is 8 bit so operations on larger datatypes are expensive. Words are still somewhat okay, but longs and floats in particular are very inefficient.
+- the syntax for boolean logical operators is 'and', 'or', 'xor', 'not'. Bitwise operators are '&', '|', '^', '~', and '<<','>>' for bit shifting left and right respectively. All operators are documents in docs/source/programming.rst
+- module imports are done using "%import modulename"
+- subroutines can return 0, 1 or more than one return value(s)
+- all variables including subroutine parameters are statically allocated exactly once; there is no call stack for variables, so recursion and reentrancy are not possible.
+- subroutines can be nested. Nested subroutines have direct access to all variables defined in their parent scope.
+- a program consists of a 'main' block containing the 'start' subroutine entry point, and zero or more other subroutines. Additional blocks and subroutines in those can be present too.
+- text output is done via the 'textio' module which defines routines such as txt.print, txt.chrout, txt.print_uw and so on.
+- math routines are in the 'math' module.
+- string to value and value to string conversion routines are in the 'conv' module.
-2. **Check startup workflow** - Execute: `read /home/irmen/Projects/prog8/.agent/workflows/startup.md`
- - This file may contain additional startup instructions
+## Project Module Descriptions
+- `beanshell` - EXPERIMENTAL/UNFINISHED Contains BeanShell integration for scripting capabilities within the compiler
+- `benchmark-c` - C implementations for performance comparison and benchmarking
+- `benchmark-program` - Benchmark programs to test compiler output performance
+- `codeCore` - Core code generation utilities and shared components
+- `codeGenCpu6502` - 6502 CPU-specific code generator backend (generates assembly for 6502-based systems)
+- `codeGenExperimental` - Experimental code generators that are under development
+- `codeGenIntermediate` - Intermediate representation (IR) code generator
+- `codeGenVirtual` - Virtual machine code generator backend
+- `codeOptimizers` - Optimization passes for improving generated code efficiency
+- `compiler` - Main compiler executable and top-level compiler logic
+- `compilerAst` - complicated Abstract Syntax Tree (AST) where most optimizations also run on, is later transformed into the simpleAst
+- `docs` - Documentation files for the Prog8 language and compiler
+- `examples` - Example Prog8 programs demonstrating language features
+- `intermediate` - Components related to the intermediate representation (IR) of Prog8 programs
+- `languageServer` - Language Server Protocol implementation for IDE integration
+- `parser` - ANTLR4 Parser implementation for the Prog8 language syntax
+- `scripts` - Utility scripts for development, testing, and deployment
+- `simpleAst` - Simplified AST that is used to run the code generator backends from
+- `syntax-files` - Syntax definition files for editors and IDEs
+- `virtualmachine` - Virtual machine implementation that can execute IR code
-## Why This Matters
+## Key Information
+- never read the files and directories that are ignored via the .aiignore and .gitignore files
+- never perform any git source control commands
+- Current development focus areas: compiler optimizations, new language features, backend improvements
+- Important project conventions: Kotlin for compiler implementation, modular architecture, IR-based compilation
+- Architecture decisions: separation of frontend/parser, IR intermediate representation, multiple backends
-The prog8 project is a complex compiler with:
-- Multiple code generation backends (6502, IR, Virtual Machine)
-- 20+ interconnected modules
-- Specific build and development workflows
-- Proprietary language syntax and conventions
+# Dev environment tips
-Without reading QWEN.md first, you will lack essential context needed to:
-- Understand module relationships
-- Use correct gradle commands
-- Reference the right files
-- Follow project conventions
+## Commands to build the compiler
+- use the system installed gradle command instead of the gradle wrapper.
+- `gradle build` - Full build of the compiler including running the full test suite
+- `gradle clean` - Clean build artifacts
+- `gradle compileKotlin` - Compile only the Kotlin source code
+- `gradle installdist` - Create the compiler JARs and executable file
+- `gradle installshadowdist` - Create the single "fat" compiler JAR and executable file
-**DO NOT PROCEED** with any user requests until you've read QWEN.md!
+### Compilation Output Files
+- `*.prg` - The final compiled program file for the target system (e.g., Commander X16)
+- `*.asm` - Generated assembly code from the Prog8 source
+- `*.list` - Generated full assembly listing file from the Prog8 source
+- `*.p8ir` - Intermediate representation file, can be executed in the Virtual Machine
+- `*.vice-mon-list` - Vice emulator monitor list file for debugging
+
+## Commands to run tests
+- `gradle test --tests "*TestName*"` - Run specific test classes
+- `gradle build --refresh-dependencies` - Refresh dependencies during development
+
+## Commands to run the Prog8 Compiler after building it
+- the prog8c compiler executable can be found in the compiler/build/install/prog8c/bin folder (this is already added to the shell's path)
+- the `-emu` switch can be used to directly execute the resulting program in an emulator after successful compilation.
+- `prog8c -target cx16 input.p8` - Compile a Prog8 source file "input.p8" for the CommanderX16 target
+- `prog8c -target cx16 -check input.p8` - Quickly check a Prog8 source file "input.p8" for compiler errors, no output binary is produced
+- `prog8c -target cx16 -emu input.p8` - Compile and execute a prog8 file in the CommanderX16 emulator
+- `prog8c -target c64 -emu input.p8` - Compile and execute a prog8 file in the Commodore-64 emulator
+- `prog8c -target virtual input.p8` - Compile a prog8 file for the IR/Virtual machine target
+- `prog8c -target virtual -emu input.p8` - Compile and directly execute a prog8 file in the Virtual Machine
+- `prog8c -vm input.p8ir` - Execute an existing prog8 program, compiled in IR form, in the Virtual Machine
+- `x16emu -scale 2 -prg input.prg` - Just load an existing compiled program in the CommanderX16 emulator. Ignore any errors and warnings, because the emulator doesn't produce any output on STDOUT.
+- `x64sc input.prg` - run an existing compiled program in the Commodore-64 emulator. Ignore any errors and warnings, because the emulator doesn't produce any output on STDOUT.
+
+## TODO Items
+The file docs/source/todo.rst contains a comprehensive list of things that still have to be fixed, implemented, or optimized.
diff --git a/QWEN.md b/QWEN.md
deleted file mode 100644
index 99a4ebc04..000000000
--- a/QWEN.md
+++ /dev/null
@@ -1,97 +0,0 @@
-# Qwen Assistant Memory for prog8 Project
-
-This file contains project-specific information that helps the Qwen assistant understand and work effectively with the prog8 codebase.
-
-## Project Overview
-- This project is a compiler for the Prog8 programming language.
-- Prog8 is a programming language primarily targeting 8-bit retro systems with the 6502 CPU, such as the Commodore 64, Commodore 128, and Commander X16.
-- The compiler has a 6502 code generator backend, and an IR code generator.
-- The IR code is meant to be used in a new machine specific code generator backend (primarily 6502 but maybe 68000 as well later)
-- The compiler includes a simple 'virtual machine' that can execute the IR code directly via interpretation.
-- Prog8 source files have .p8 extension
-- Prog8 source files are a "module" that can contain 1 ore more "blocks". They can also import other modules, from internal library files or from source files on the filesystem.
-- The prog8 compiler is written mostly in Kotlin, those files have the .kt extension.
-
-## Prog8 language feature hints
-- an overview of the language features can be found in the documentation file docs/source/introduction.rst
-- the syntax and grammar is specified in an ANTLR4 grammar file found in the parser directory
-- available primitive datatypes are bool, byte, ubyte, word, uword, long and float. ubyte and uword are unsigned the others are signed. The long type is 4 bytes and the float type is 5-byte "Microsoft" floating point.
-- there is a str type which is a 0-terminated string consisting of ubytes
-- there are also arrays, and pointers. Pointer notation differs from C.
-- there are also structs which can contain primitive types. Prog8 does not yet have by-value struct variables, only pointer to structs.
-- while there are larger than byte datatypes, the intended compiler target is a 6502 CPU system which is 8 bit so operations on larger datatypes are expensive. Words are still somewhat okay, but longs and floats in particular are very inefficient.
-- the syntax for boolean logical operators is 'and', 'or', 'xor', 'not'. Bitwise operators are '&', '|', '^', '~', and '<<','>>' for bit shifting left and right respectively. All operators are documents in docs/source/programming.rst
-- module imports are done using "%import modulename"
-- subroutines can return 0, 1 or more than one return value(s)
-- all variables including subroutine parameters are statically allocated exactly once; there is no call stack for variables, so recursion and reentrancy are not possible.
-- subroutines can be nested. Nested subroutines have direct access to all variables defined in their parent scope.
-- a program consists of a 'main' block containing the 'start' subroutine entry point, and zero or more other subroutines. Additional blocks and subroutines in those can be present too.
-- text output is done via the 'textio' module which defines routines such as txt.print, txt.chrout, txt.print_uw and so on.
-- math routines are in the 'math' module.
-- string to value and value to string conversion routines are in the 'conv' module.
-
-## Module Descriptions
-- `beanshell` - EXPERIMENTAL/UNFINISHED Contains BeanShell integration for scripting capabilities within the compiler
-- `benchmark-c` - C implementations for performance comparison and benchmarking
-- `benchmark-program` - Benchmark programs to test compiler output performance
-- `codeCore` - Core code generation utilities and shared components
-- `codeGenCpu6502` - 6502 CPU-specific code generator backend (generates assembly for 6502-based systems)
-- `codeGenExperimental` - Experimental code generators that are under development
-- `codeGenIntermediate` - Intermediate representation (IR) code generator
-- `codeGenVirtual` - Virtual machine code generator backend
-- `codeOptimizers` - Optimization passes for improving generated code efficiency
-- `compiler` - Main compiler executable and top-level compiler logic
-- `compilerAst` - complicated Abstract Syntax Tree (AST) where most optimizations also run on, is later transformed into the simpleAst
-- `docs` - Documentation files for the Prog8 language and compiler
-- `examples` - Example Prog8 programs demonstrating language features
-- `intermediate` - Components related to the intermediate representation (IR) of Prog8 programs
-- `languageServer` - Language Server Protocol implementation for IDE integration
-- `parser` - ANTLR4 Parser implementation for the Prog8 language syntax
-- `scripts` - Utility scripts for development, testing, and deployment
-- `simpleAst` - Simplified AST that is used to run the code generator backends from
-- `syntax-files` - Syntax definition files for editors and IDEs
-- `virtualmachine` - Virtual machine implementation that can execute IR code
-
-## Key Information
-- never read the files and directories that are ignored via the .aiignore and .gitignore files
-- Current development focus areas: compiler optimizations, new language features, backend improvements
-- Important project conventions: Kotlin for compiler implementation, modular architecture, IR-based compilation
-- Architecture decisions: separation of frontend/parser, IR intermediate representation, multiple backends
-
-### Gradle Commands
-- use the system installed gradle command instead of the gradle wrapper.
-- `gradle build` - Full build of the compiler including running the full test suite
-- `gradle clean` - Clean build artifacts
-- `gradle compileKotlin` - Compile only the Kotlin source code
-- `gradle installdist` - Create the compiler JARs and executable file
-- `gradle installshadowdist` - Create the single "fat" compiler JAR and executable file
-
-### Development Shortcuts
-- `gradle test --tests "*TestName*"` - Run specific test classes
-- `gradle build --refresh-dependencies` - Refresh dependencies during development
-
-### Prog8 Compiler Usage
-- the prog8c compiler executable can be found in the compiler/build/install/prog8c/bin folder (this is already added to the shell's path)
-- the `-emu` switch can be used to directly execute the resulting program in an emulator after successful compilation.
-- `prog8c -target cx16 input.p8` - Compile a Prog8 source file "input.p8" for the CommanderX16 target
-- `prog8c -target cx16 -check input.p8` - Quickly check a Prog8 source file "input.p8" for compiler errors, no output binary is produced
-- `prog8c -target cx16 -emu input.p8` - Compile and execute a prog8 file in the CommanderX16 emulator
-- `prog8c -target c64 -emu input.p8` - Compile and execute a prog8 file in the Commodore-64 emulator
-- `prog8c -target virtual input.p8` - Compile a prog8 file for the IR/Virtual machine target
-- `prog8c -target virtual -emu input.p8` - Compile and directly execute a prog8 file in the Virtual Machine
-- `prog8c -vm input.p8ir` - Execute an existing prog8 program, compiled in IR form, in the Virtual Machine
-- `x16emu -scale 2 -prg input.prg` - Just load an existing compiled program in the CommanderX16 emulator
-- `x64sc input.prg` - run an existing compiled program in the Commodore-64 emulator (Note: You can safely ignore errors and warnings from this emulator)
-
-### Compilation Output Files
-- `*.prg` - The final compiled program file for the target system (e.g., Commander X16)
-- `*.asm` - Generated assembly code from the Prog8 source
-- `*.list` - Generated full assembly listing file from the Prog8 source
-- `*.p8ir` - Intermediate representation file, can be executed in the Virtual Machine
-- `*.vice-mon-list` - Vice emulator monitor list file for debugging
-
-## Working Notes
-[Any ongoing notes about the project that would be helpful for the assistant to remember]
-
-## TODO Items
-The file docs/source/todo.rst contains a comprehensive list of things that still have to be fixed, implemented, or optimized.
diff --git a/README.md b/README.md
index 7c9e62208..94920cd7c 100644
--- a/README.md
+++ b/README.md
@@ -205,3 +205,10 @@ Here is a performance comparison with various C compilers for the 6502/C64 so yo
an idea of how Prog8 stacks up.
[comparison](benchmark-c/benchmark.md)
+
+
+Agent context instructions
+--------------------------
+
+[Agent context instructions](AGENTS.md)
+
diff --git a/build.gradle.kts b/build.gradle.kts
index 108cf95ad..5276fa16a 100644
--- a/build.gradle.kts
+++ b/build.gradle.kts
@@ -5,7 +5,7 @@ import org.jetbrains.kotlin.gradle.dsl.KotlinVersion
plugins {
- kotlin("jvm") version "2.3.0"
+ kotlin("jvm") version "2.3.10"
}
allprojects {
diff --git a/docs/source/todo.rst b/docs/source/todo.rst
index 741bc5179..848c573b1 100644
--- a/docs/source/todo.rst
+++ b/docs/source/todo.rst
@@ -41,7 +41,7 @@ Future Things and Ideas
- Make all constants long by default? or not? (remove type name altogether), reduce to target type implictly if the actual value fits. Experiment is in branch 'long-consts'
This will break some existing programs that depend on value wrap arounds, but gives more intuitive constant number handling.
Can give descriptive error message for old syntax that still includes the type name?
-- improve ANTLR grammar with better error handling (as suggested by Qwen AI)
+- improve ANTLR grammar with better error handling
- add documentation for more library modules instead of just linking to the source code
- add an Index to the documentation
- can we just use index numbers instead of object hashes for struct instance labels (and other places?) see labelnameForStructInstance
diff --git a/languageServer/build.gradle.kts b/languageServer/build.gradle.kts
index 8b95f40b1..eec832641 100644
--- a/languageServer/build.gradle.kts
+++ b/languageServer/build.gradle.kts
@@ -31,8 +31,8 @@ repositories {
}
dependencies {
- implementation("org.eclipse.lsp4j:org.eclipse.lsp4j:0.24.0")
- implementation("org.eclipse.lsp4j:org.eclipse.lsp4j.jsonrpc:0.24.0")
+ implementation("org.eclipse.lsp4j:org.eclipse.lsp4j:1.0.0")
+ implementation("org.eclipse.lsp4j:org.eclipse.lsp4j.jsonrpc:1.0.0")
// For JSON processing if needed
//implementation("com.google.code.gson:gson:2.10.1")