prog8/README.md

155 lines
6.8 KiB
Markdown
Raw Normal View History

2020-03-15 00:49:16 +00:00
[![Documentation](https://readthedocs.org/projects/prog8/badge/?version=latest)](https://prog8.readthedocs.io/)
2019-06-21 21:22:34 +00:00
2020-08-27 16:18:29 +00:00
Prog8 - Structured Programming Language for 8-bit 6502/65c02 microprocessors
============================================================================
2017-12-21 13:52:30 +00:00
2018-01-09 23:44:11 +00:00
*Written by Irmen de Jong (irmen@razorvine.net)*
2017-12-21 13:52:30 +00:00
This is a structured programming language for the 8-bit 6502/6510/65c02 microprocessor from the late 1970's and 1980's
2018-09-15 14:21:05 +00:00
as used in many home computers from that era. It is a medium to low level programming language,
2020-08-30 16:32:16 +00:00
which aims to provide many conveniences over raw assembly code (even when using a macro assembler).
2017-12-25 15:00:25 +00:00
2020-08-30 16:32:16 +00:00
Documentation
-------------
Full documentation (syntax reference, how to use the language and the compiler, etc.) can be found at:
https://prog8.readthedocs.io/
2021-05-02 13:31:14 +00:00
Software license
----------------
GNU GPL 3.0, see file LICENSE
- prog8 (the compiler + libraries) is licensed under GNU GPL 3.0
- *exception:* the resulting files created by running the compiler are free to use in whatever way desired.
2020-08-30 16:32:16 +00:00
2020-11-26 01:04:01 +00:00
What does Prog8 provide?
------------------------
2020-08-30 16:32:16 +00:00
2021-02-28 14:40:04 +00:00
- reduction of source code length over raw assembly
2021-04-04 10:55:29 +00:00
- fast execution speed due to compilation to native assembly code. It's possible to write certain raster interrupt 'demoscene' effects purely in Prog8.
2017-12-25 15:00:25 +00:00
- modularity, symbol scoping, subroutines
- various data types other than just bytes (16-bit words, floats, strings)
2021-04-29 17:57:14 +00:00
- floating point math is supported if the target system provides floating point library routines (C64 and Cx16 both do)
2021-05-07 13:28:22 +00:00
- strings can contain escaped characters but also many symbols directly if they have a petscii equivalent, such as "♠♥♣♦π▚●○╳". Characters like ^, _, \, {, } and | are also accepted and converted to the closest petscii equivalents.
2021-04-04 10:55:29 +00:00
- automatic static variable allocations, automatic string and array variables and string sharing
2021-02-28 14:40:04 +00:00
- subroutines with input parameters and result values
- high-level program optimizations
- small program boilerplate/compilersupport overhead
2021-04-29 17:57:14 +00:00
- programs can be run multiple times without reloading because of automatic variable (re)initializations.
2019-06-21 21:41:20 +00:00
- conditional branches
2021-12-29 17:24:05 +00:00
- ``when`` statement to provide a concise jump table alternative to if/elseif chains
- ``in`` expression for concise and efficient multi-value/containment check
2021-01-13 21:48:59 +00:00
- many built-in functions such as ``sin``, ``cos``, ``rnd``, ``abs``, ``min``, ``max``, ``sqrt``, ``msb``, ``rol``, ``ror``, ``swap``, ``sort`` and ``reverse``
- various powerful built-in libraries to do I/O, number conversions, graphics and more
2020-11-30 21:42:51 +00:00
- convenience abstractions for low level aspects such as ZeroPage handling, program startup, explicit memory addresses
2019-07-23 22:43:37 +00:00
- inline assembly allows you to have full control when every cycle or byte matters
2021-04-29 17:57:14 +00:00
- supports the sixteen 'virtual' 16-bit registers R0 - R15 from the Commander X16, and provides them also on the C64.
2021-02-28 14:40:04 +00:00
- encode strings and characters into petscii or screencodes as desired (C64/Cx16)
2019-06-21 21:41:20 +00:00
2020-08-30 16:32:16 +00:00
*Rapid edit-compile-run-debug cycle:*
2019-06-21 21:41:20 +00:00
2020-11-26 01:04:01 +00:00
- use a modern PC to do the work on, use nice editors and enjoy quick compilation times
- can automatically run the program in the Vice emulator after succesful compilation
2017-12-27 22:45:22 +00:00
- breakpoints, that let the Vice emulator drop into the monitor if execution hits them
- source code labels automatically loaded in Vice emulator so it can show them in disassembly
2017-12-25 15:00:25 +00:00
2021-12-21 23:36:06 +00:00
*Multiple supported compiler targets* (contributions to improve these or to add support for other machines are welcome!):
2020-08-30 16:32:16 +00:00
2021-12-21 23:36:06 +00:00
- "c64": Commodore-64 (6502 like CPU)
- "c128": Commodore-128 (6502 like CPU - the Z80 cpu mode is not supported)
2021-01-13 21:48:59 +00:00
- "cx16": [CommanderX16](https://www.commanderx16.com) (65c02 CPU)
2021-12-21 23:36:06 +00:00
- If you only use standard kernal and prog8 library routines, it is possible to compile the *exact same program* for different machines (just change the compiler target flag)
2017-12-25 15:00:25 +00:00
2019-01-26 17:56:53 +00:00
2020-08-30 16:32:16 +00:00
Additional required tools
-------------------------
2017-12-25 15:00:25 +00:00
2019-01-26 17:59:14 +00:00
[64tass](https://sourceforge.net/projects/tass64/) - cross assembler. Install this on your shell path.
A recent .exe version of this tool for Windows can be obtained from my [clone](https://github.com/irmen/64tass/releases) of this project.
2019-01-26 17:41:25 +00:00
For other platforms it is very easy to compile it yourself (make ; make install).
2020-11-26 01:04:01 +00:00
A **Java runtime (jre or jdk), version 11 or newer** is required to run a prepackaged version of the compiler.
2019-06-21 21:41:20 +00:00
If you want to build it from source, you'll need a Java SDK + Kotlin 1.3.x SDK (or for instance,
2019-01-26 17:41:25 +00:00
IntelliJ IDEA with the Kotlin plugin).
It's handy to have an emulator (or a real machine perhaps!) to run the programs on. The compiler assumes the presence
of the [Vice emulator](http://vice-emu.sourceforge.net/) for the C64 target,
and the [x16emu emulator](https://github.com/commanderx16/x16-emulator) for the CommanderX16 target.
2019-01-26 17:41:25 +00:00
Example code
------------
2019-04-12 20:34:43 +00:00
This code calculates prime numbers using the Sieve of Eratosthenes algorithm::
2019-01-26 17:41:25 +00:00
2020-09-21 16:21:24 +00:00
%import textio
2019-04-12 20:34:43 +00:00
%zeropage basicsafe
2020-09-21 16:21:24 +00:00
2019-08-05 19:11:58 +00:00
main {
2020-09-21 16:21:24 +00:00
2019-04-12 20:34:43 +00:00
ubyte[256] sieve
2020-09-21 16:21:24 +00:00
ubyte candidate_prime = 2 ; is increased in the loop
2019-01-26 17:41:25 +00:00
sub start() {
2021-01-13 21:48:59 +00:00
sys.memset(sieve, 256, false) ; clear the sieve
2020-08-27 16:10:22 +00:00
txt.print("prime numbers up to 255:\n\n")
2019-04-12 20:34:43 +00:00
ubyte amount=0
2020-07-26 11:50:14 +00:00
repeat {
2019-04-12 20:34:43 +00:00
ubyte prime = find_next_prime()
if prime==0
break
2020-08-27 16:10:22 +00:00
txt.print_ub(prime)
txt.print(", ")
2019-04-12 20:34:43 +00:00
amount++
}
2021-01-13 21:48:59 +00:00
txt.nl()
2020-08-27 16:10:22 +00:00
txt.print("number of primes (expected 54): ")
txt.print_ub(amount)
2021-01-13 21:48:59 +00:00
txt.nl()
2019-01-26 17:41:25 +00:00
}
2020-09-21 16:21:24 +00:00
2019-04-12 20:34:43 +00:00
sub find_next_prime() -> ubyte {
while sieve[candidate_prime] {
candidate_prime++
if candidate_prime==0
2021-01-13 21:48:59 +00:00
return 0 ; we wrapped; no more primes
2019-04-12 20:34:43 +00:00
}
2020-09-21 16:21:24 +00:00
2020-08-27 16:10:22 +00:00
; found next one, mark the multiples and return it.
2019-04-12 20:34:43 +00:00
sieve[candidate_prime] = true
uword multiple = candidate_prime
2020-09-21 16:21:24 +00:00
2019-04-12 20:34:43 +00:00
while multiple < len(sieve) {
sieve[lsb(multiple)] = true
multiple += candidate_prime
}
return candidate_prime
}
}
2019-01-26 17:45:17 +00:00
2020-09-21 16:21:24 +00:00
2021-01-13 21:48:59 +00:00
2019-04-12 20:34:43 +00:00
when compiled an ran on a C-64 you'll get:
2019-01-26 17:41:25 +00:00
2019-04-12 20:34:43 +00:00
![c64 screen](docs/source/_static/primes_example.png)
2019-01-26 18:13:42 +00:00
One of the included examples (wizzine.p8) animates a bunch of sprite balloons and looks like this:
![wizzine screen](docs/source/_static/wizzine.png)
Another example (cube3d-sprites.p8) draws the vertices of a rotating 3d cube:
![cube3d screen](docs/source/_static/cube3d.png)
2019-03-10 04:38:14 +00:00
If you want to play a video game, a fully working Tetris clone is included in the examples:
![tehtriz_screen](docs/source/_static/tehtriz.png)
2020-09-18 21:34:32 +00:00
2021-01-13 21:48:59 +00:00
There are a couple of examples specially made for the CommanderX16 compiler target.
For instance here's a well known space ship animated in 3D with hidden line removal,
in the CommanderX16 emulator:
2020-09-18 21:34:32 +00:00
![cobra3d](docs/source/_static/cobra3d.png)