prog8/README.md

189 lines
9.0 KiB
Markdown
Raw Normal View History

[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/H2H6S0FFF)
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
**Want to buy me a coffee or a pizza perhaps?**
This project was created over the last couple of years by dedicating thousands of hours of my free time to it, to make it the best I possibly can.
If you like Prog8, and think it's worth a nice cup of hot coffee or a delicious pizza,
you can help me out a little bit over at [ko-fi.com/irmen](https://ko-fi.com/irmen).
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/
2023-07-04 20:41:38 +00:00
How to get it/build it
----------------------
- Download the latest [official release](https://github.com/irmen/prog8/releases) from github.
- Or, if you want/need a bleeding edge development version, you can:
- download a build artifact zipfile from a recent [github action build](https://github.com/irmen/prog8/actions).
- you can also compile it yourself from source. [Instructions here](https://prog8.readthedocs.io/en/latest/compiling.html).
- Alternatively, you can also install the compiler as a package on some linux distros:
- Arch (via AUR): [`prog8`](https://aur.archlinux.org/packages/prog8)
2023-07-04 20:41:38 +00:00
2023-07-04 21:50:16 +00:00
Community
---------
Most of the development on Prog8 and the use of it is currently centered around
the [Commander X16](https://www.commanderx16.com/) retro computer. Their [discord server](https://discord.gg/nS2PqEC) contains a small channel
dedicated to Prog8. Other than that, use the issue tracker on github.
2023-07-04 20:41:38 +00:00
2021-05-02 13:31:14 +00:00
Software license
----------------
GNU GPL 3.0 (see file LICENSE), with exception for generated code:
2021-05-02 13:31:14 +00:00
- The compiler and its libraries are free to use according to the terms of the GNU GPL 3.0
- *exception:* the resulting files (intermediate source codes and resulting binary program) created by the compiler
are excluded from the GPL and are free to use in whatever way desired, commercially or not.
2021-05-02 13:31:14 +00:00
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
2024-02-26 00:17:25 +00:00
- all advantages of a higher level language over having to write assembly code manually
- programs run very fast because compilation to native machine code. It's possible to write games purely in Prog8, and even certain raster interrupt 'demoscene' effects.
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
2024-02-26 00:17:25 +00:00
- no need for forward declarations
2021-02-28 14:40:04 +00:00
- 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)
2023-08-12 21:24:41 +00:00
- "pet32": Commodore PET (experimental)
- "atari": Atari 8 bit such as 800XL (experimental)
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 a recent emulator version (R42 or newer) for the CommanderX16, such as [x16emu](https://cx16forum.com/forum/viewforum.php?f=30)
(preferred, this is the official emulator. If required, source code is [here](https://github.com/X16Community/x16-emulator/)).
There is also [Box16](https://github.com/indigodarkwolf/box16) which has powerful debugging features.
2019-01-26 17:41:25 +00:00
**Syntax highlighting:** for a few different editors, syntax highlighting definition files are provided.
Look in the [syntax-files](https://github.com/irmen/prog8/tree/master/syntax-files) directory in the github repository to find them.
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)