prog8/docs/source/index.rst

213 lines
8.8 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,
2022-10-28 21:45:09 +00:00
such as the `Commodore 64 <https://en.wikipedia.org/wiki/Commodore_64>`_.
2018-08-06 01:35:43 +00:00
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 (release R42 or newer is required)
2022-03-02 22:31:07 +00:00
* 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
2022-05-02 17:46:08 +00:00
**License:**
This software is free to use, as defined in the GNU GPL 3.0 (https://www.gnu.org/licenses/gpl.html)
*Exception:* All output files generated by the compiler (intermediary files and compiled binary programs)
are excluded from this and you can do with those *whatever you want*.
This means, for instance, that you can use the Prog8 compiler to create commercial software as long as only sell *the actual resulting program*.
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
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.
2023-04-28 16:18:41 +00:00
- Floating point math also supported on select compiler targets (C64, Cx16 and virtual).
2022-10-29 12:07:04 +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.
2022-12-08 21:21:45 +00:00
- High-level code optimizations, such as const-folding (zero-allocation constants that are optimized away in expressions), expression and statement simplifications/rewriting.
- Many built-in functions, such as ``sin``, ``cos``, ``abs``, ``sqrt``, ``msb``, ``min``, ``max``, ``rol``, ``ror``, ``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.
2022-10-29 12:10:11 +00:00
- 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
2022-10-28 21:49:23 +00:00
%zeropage basicsafe
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
2022-10-29 12:12:10 +00:00
when compiled an ran on a C64 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
2022-10-29 12:12:10 +00:00
:alt: result when run on C64
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
2023-04-03 18:47:31 +00:00
`64tass <https://sourceforge.net/projects/tass64/>`_ - cross assembler. Install this program somewhere on your shell's search path.
It's easy to compile yourself, but a recent precompiled .exe (only for Windows) can be obtained from
`the files section <https://sourceforge.net/projects/tass64/files/binaries/>`_ in the official project on sourceforge.
2023-06-16 21:24:31 +00:00
*You need at least version 1.58.0 of this assembler.*
2023-04-03 18:47:31 +00:00
If you are on a Debian based Linux, there's a "64tass" package in the repositories, which is a bit old, but it seems to work.
It's possible to use old versions of 64tass, but it is likely that certain things will break.
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.
2023-01-21 13:47:32 +00:00
If you're scared of Oracle's licensing terms, most Linux distributions ship OpenJDK or similar in their packages repository instead.
For Windows it's possible to get that as well; check out `Adoptium <https://adoptium.net/temurin/releases/?version=11>`_ .
For MacOS you can use the Homebrew system to install a recent version of OpenJDK.
2019-01-24 01:43:25 +00:00
2022-10-28 21:39:54 +00:00
Finally: an **emulator** (or a real machine of course) to test and run your programs on.
2022-10-29 12:12:10 +00:00
In C64 mode, the compiler assumes the presence of the `VICE emulator <http://vice-emu.sourceforge.net/>`_.
If you're targeting the Commander X16 instead,
download 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.
You can select which one you want to launch using the ``-emu`` or ``-emu2`` command line options.
**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.
2018-08-06 01:35:43 +00:00
.. toctree::
:maxdepth: 2
:caption: Contents of this manual:
2023-06-25 19:35:30 +00:00
compiling.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
2023-05-16 21:10:33 +00:00
upgrading8.rst
2018-08-06 01:35:43 +00:00
todo.rst
Index
=====
* :ref:`genindex`