prog8/docs/source/index.rst

216 lines
9.0 KiB
ReStructuredText
Raw Normal View History

2018-09-15 14:21:05 +00:00
Prog8 documentation - |version|
===============================
2018-08-06 01:35:43 +00:00
.. image:: _static/logo.jpg
:align: center
2018-09-15 14:21:05 +00:00
:alt: Prog8 logo
2018-08-06 01:35:43 +00:00
2018-09-15 14:21:05 +00:00
.. index:: what is Prog8
2018-08-06 01:35:43 +00:00
2018-09-15 14:21:05 +00:00
What is Prog8?
--------------
2018-08-06 01:35:43 +00:00
2020-12-22 15:44:05 +00:00
This is a compiled programming language targeting the 8-bit
2018-08-06 01:35:43 +00:00
`6502 <https://en.wikipedia.org/wiki/MOS_Technology_6502>`_ /
2020-12-22 15:44:05 +00:00
`6510 <https://en.wikipedia.org/wiki/MOS_Technology_6510>`_ /
`65c02 <https://en.wikipedia.org/wiki/MOS_Technology_65C02>`_ microprocessors.
2018-08-06 01:35:43 +00:00
This CPU is 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>`_.
The language aims to provide many conveniences over raw assembly code (even when using a macro assembler),
while still being low level enough to create high performance programs.
2022-03-02 22:31:07 +00:00
You can compile programs for various machines with this CPU:
* Commodore 64
* Commander X16
* Commodore 128 (limited support for now)
* Atari 800 XL (limited support for now)
2018-08-06 01:35:43 +00:00
2018-09-15 14:21:05 +00:00
Prog8 is copyright © Irmen de Jong (irmen@razorvine.net | http://www.razorvine.net).
2019-01-26 17:56:53 +00:00
The project is on github: https://github.com/irmen/prog8.git
2018-08-06 01:35:43 +00:00
2019-01-26 17:56:53 +00:00
This software is licensed under the GNU GPL 3.0, see https://www.gnu.org/licenses/gpl.html
2018-08-06 01:35:43 +00:00
.. image:: _static/cube3d.png
:width: 33%
:alt: 3d rotating sprites
.. image:: _static/wizzine.png
:width: 33%
:alt: Simple wizzine sprite effect
.. image:: _static/tehtriz.png
:width: 33%
:alt: Fully playable tetris clone
2020-11-30 21:42:51 +00:00
Language features
-----------------
- It is a cross-compiler running on modern machines (Linux, MacOS, Windows, ...)
2021-04-04 10:55:29 +00:00
It generates a machine code program runnable on actual 8-bit 6502 hardware.
- Fast execution speed due to compilation to native assembly code. It's possible to write certain raster interrupt 'demoscene' effects purely in Prog8.
- Provides a very convenient edit/compile/run cycle by being able to directly launch
2020-11-30 21:42:51 +00:00
the compiled program in an emulator and provide debugging information to this emulator.
- Based on simple and familiar imperative structured programming (it looks like a mix of C and Python)
- Modular programming and scoping via modules, code blocks, and subroutines.
- Provide high level programming constructs but at the same time stay close to the metal;
still able to directly use memory addresses and ROM subroutines,
and inline assembly to have full control when every register, cycle or byte matters
2021-02-28 14:40:04 +00:00
- Subroutines with parameters and return values
2021-04-29 17:57:14 +00:00
- Complex nested expressions are possible
2021-02-28 14:40:04 +00:00
- Variables are allocated statically
2021-12-29 17:24:05 +00:00
- Conditional branches to map directly on processor branch instructions
- ``when`` statement to avoid if-else chains
- ``in`` expression for concise and efficient multi-value/containment test
2022-01-06 21:45:36 +00:00
- pipe operator ``|>`` to rewrite nested function call expressions in a more readable chained form
2020-11-30 21:42:51 +00:00
- Nested subroutines can access variables from outer scopes to avoids the overhead to pass everything via parameters
2021-04-29 17:57:14 +00:00
- Variable data types include signed and unsigned bytes and words, arrays, strings.
- Floating point math also 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.
2020-11-30 21:42:51 +00:00
- High-level code optimizations, such as const-folding, expression and statement simplifications/rewriting.
- Many built-in functions, such as ``sin``, ``cos``, ``rnd``, ``abs``, ``min``, ``max``, ``sqrt``, ``msb``, ``rol``, ``ror``, ``swap``, ``sort`` and ``reverse``
2021-04-04 10:55:29 +00:00
- Programs can be run multiple times without reloading because of automatic variable (re)initializations.
2021-12-30 17:33:26 +00:00
- Supports the sixteen 'virtual' 16-bit registers R0 .. R15 from the Commander X16, also on the other machines.
- If you only use standard kernal and core prog8 library routines, it is possible to compile the *exact same program* for different machines (just change the compilation target flag)!
2020-11-30 21:42:51 +00:00
2020-09-23 16:50:32 +00:00
Code example
------------
2019-01-24 01:43:25 +00:00
Here is a hello world program::
%import textio
main {
sub start() {
txt.print("hello world i ♥ prog8\n")
}
}
2019-04-12 20:34:43 +00:00
This code calculates prime numbers using the Sieve of Eratosthenes algorithm::
2019-01-24 01:43:25 +00:00
2020-09-21 16:21:24 +00:00
%import textio
2021-01-08 00:31:28 +00:00
%zeropage basicsafe
2019-01-24 01:43:25 +00:00
2019-07-29 21:11:13 +00:00
main {
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-04-12 20:34:43 +00:00
2019-01-24 01:43:25 +00:00
sub start() {
2020-09-21 16:21:24 +00:00
; clear the sieve, to reset starting situation on subsequent runs
sys.memset(sieve, 256, false)
2020-09-21 16:21:24 +00:00
; calculate primes
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-08 15:56:17 +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-08 15:56:17 +00:00
txt.nl()
}
2019-01-24 01:43:25 +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
2020-09-21 16:21:24 +00:00
return 0 ; we wrapped; no more primes available in the sieve
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-08-27 16:10:22 +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:44:30 +00:00
when compiled an ran on a C-64 you get this:
2019-01-24 01:43:25 +00:00
2019-04-12 20:34:43 +00:00
.. image:: _static/primes_example.png
:align: center
:alt: result when run on C-64
2019-01-24 01:43:25 +00:00
2020-10-05 17:59:51 +00:00
when the exact same program is compiled for the Commander X16 target, and run on the emulator, you get this:
.. image:: _static/primes_cx16.png
:align: center
:alt: result when run on CX16 emulator
2019-01-24 01:43:25 +00:00
Getting the compiler
--------------------
Usually you just download a fat jar of an official released version, but you can also build
it yourself from source.
Detailed instructions on how to obtain a version of the compiler are in :ref:`building_compiler`.
.. _requirements:
Required additional tools
-------------------------
2018-08-06 01:35:43 +00:00
2019-01-24 01:43:25 +00:00
`64tass <https://sourceforge.net/projects/tass64/>`_ - cross assembler. Install this on your shell path.
2020-03-14 14:19:03 +00:00
It's very easy to compile yourself.
2020-12-22 12:29:16 +00:00
A recent precompiled .exe (only for Windows) can be obtained from my `clone <https://github.com/irmen/64tass/releases>`_ of this project.
*You need at least version 1.55.2257 of this assembler to correctly use the breakpoints feature.*
It's possible to use older versions, but it is very likely that the automatic Vice breakpoints won't work with them.
2019-01-24 01:43:25 +00:00
A **Java runtime (jre or jdk), version 11 or newer** is required to run the prog8 compiler itself.
If you're scared of Oracle's licensing terms, most Linux distributions ship OpenJDK in their packages repository instead.
For Windows it's possible to get that as well; check out `AdoptOpenJDK <https://adoptopenjdk.net/>`_ .
For MacOS you can use the Homebrew system to install a recent version of OpenJDK.
2019-01-24 01:43:25 +00:00
Finally: an **emulator** (or a real machine ofcourse) to test and run your programs on.
In C64 mode, the compiler assumes the presence of the `Vice emulator <http://vice-emu.sourceforge.net/>`_.
If you're targeting the CommanderX16 instead, there's a choice of the official `x16emu <https://github.com/commanderx16/x16-emulator>`_
and the unofficial `box16 <https://github.com/indigodarkwolf/box16>`_ (you can select which one you want to launch
using the ``-emu`` or ``-emu2`` command line options)
2021-12-30 18:05:56 +00:00
.. attention:: **Commander-X16 r38 versus r39**
2021-06-24 18:33:20 +00:00
2021-12-30 18:05:56 +00:00
Starting with Prog8 7.0 the CX16 compilation target is configured for the upcoming r39 version of the emulator
2021-06-24 18:33:20 +00:00
and roms, that are most accurately reflecting the current state of the hardware design of the CX16.
2021-12-30 18:05:56 +00:00
Unfortunately, r39 has not yet been officially released. At the time of writing, r38 is still
the latest official release. So, you have to either compile the r39 emulator+roms from the source in git yourself
2021-11-29 23:54:03 +00:00
or obtain a precompiled version from someone else. You can contact me if you require help doing this and use Linux.
2021-12-30 18:05:56 +00:00
A cx16 program compiled by prog8 7.0 is meant for r39 but *may* still work on the older v38 release of the emulator!
For this to work you should make sure that the program is not using floating point, nor the ram/rom bank switching logic provided by the libraries.
You can also choose to just stick with Prog8 6.4 (which still targets cx16 v38) and wait it out till
2021-12-30 18:05:56 +00:00
the emulator r39 is officially released - but you won't be able to benefit from the compiler improvements
2022-01-03 22:38:41 +00:00
made since that old release of prog8.
2019-01-24 01:43:25 +00:00
2018-08-06 01:35:43 +00:00
.. toctree::
:maxdepth: 2
:caption: Contents of this manual:
2018-08-06 23:23:34 +00:00
building.rst
2018-08-06 01:35:43 +00:00
programming.rst
syntaxreference.rst
libraries.rst
2021-04-04 10:55:29 +00:00
targetsystem.rst
technical.rst
portingguide.rst
2018-08-06 01:35:43 +00:00
todo.rst
Index
=====
* :ref:`genindex`