prog8/docs/source/index.rst

185 lines
7.5 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
2018-09-15 14:21:05 +00:00
This is an experimental compiled programming language targeting the 8-bit
2018-08-06 01:35:43 +00:00
`6502 <https://en.wikipedia.org/wiki/MOS_Technology_6502>`_ /
`65c02 <https://en.wikipedia.org/wiki/MOS_Technology_65C02>`_ /
2018-08-06 01:35:43 +00:00
`6510 <https://en.wikipedia.org/wiki/MOS_Technology_6510>`_ microprocessor.
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.
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-09-23 16:50:32 +00:00
Code example
------------
2019-01-24 01:43:25 +00:00
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
2019-04-12 20:34:43 +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
memset(sieve, 256, false)
; 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++
}
2020-09-21 16:21:24 +00:00
txt.chrout('\n')
2020-08-27 16:10:22 +00:00
txt.print("number of primes (expected 54): ")
txt.print_ub(amount)
2020-09-21 16:21:24 +00:00
txt.chrout('\n')
}
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
2019-01-24 01:43:25 +00:00
Design principles and features
------------------------------
2018-08-06 01:35:43 +00:00
2018-09-01 17:28:11 +00:00
- It is a cross-compiler running on modern machines (Linux, MacOS, Windows, ...)
The generated output is a machine code program runnable on actual 8-bit 6502 hardware.
2020-03-24 21:37:42 +00:00
- Based on simple and familiar imperative structured programming (it looks like a mix of C and Python)
- 'One statement per line' code, resulting in clear readable programs.
2018-09-01 17:28:11 +00:00
- Modular programming and scoping via modules, code blocks, and subroutines.
2020-03-24 21:37:42 +00:00
- 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
2020-03-24 21:37:42 +00:00
- Arbitrary number of subroutine parameters
2019-01-24 01:43:25 +00:00
- Complex nested expressions are possible
2020-03-24 21:37:42 +00:00
- Nested subroutines can access variables from outer scopes to avoids the overhead to pass everything via parameters
- Values are typed. Available data types include signed and unsigned bytes and words, arrays, strings and floats.
2019-01-24 01:43:25 +00:00
- No dynamic memory allocation or sizing! All variables stay fixed size as determined at compile time.
- Provide various quality of life language features and library subroutines specifically for the target platform.
- Provide a very convenient edit/compile/run cycle by being able to directly launch
2020-03-24 21:37:42 +00:00
the compiled program in an emulator and provide debugging information to this emulator.
2019-08-11 08:44:58 +00:00
- Arbitrary control flow jumps and branches are possible,
2019-01-24 01:43:25 +00:00
and will usually translate directly into the appropriate single 6502 jump/branch instruction.
- There are no complicated built-in error handling or overflow checks, you'll have to take care
of this yourself if required. This keeps the language and code simple and efficient.
2020-03-24 21:37:42 +00:00
- The compiler tries to optimize the program and generated code a bit, but hand-tuning of the
2019-01-24 01:43:25 +00:00
performance or space-critical parts will likely still be required. This is supported by
the ability to easily write embedded assembly code directly in the program source code.
- There are many built-in functions, such as ``sin``, ``cos``, ``rnd``, ``abs``, ``min``, ``max``, ``sqrt``, ``msb``, ``rol``, ``ror``, ``swap``, ``memset``, ``memcopy``, ``substr``, ``sort`` and ``reverse`` (and others)
2020-03-24 21:37:42 +00:00
- Assembling the generated code into a program wil be done by an external cross-assembler tool.
2020-09-21 22:47:02 +00:00
- If you only use standard kernel and prog8 library routines, it is possible to compile the *exact same program* for both machines (just change the compiler target flag)!
2018-08-06 01:35:43 +00:00
.. _requirements:
2018-08-06 01:35:43 +00:00
Required tools
--------------
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.
A recent precompiled .exe 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
2020-03-14 14:19:03 +00:00
A **Java runtime (jre or jdk), version 8 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, thhe compiler assumes the presence of the `Vice emulator <http://vice-emu.sourceforge.net/>`_.
If you're targeting the CommanderX16 instead, there's the `x16emu <https://github.com/commanderx16/x16-emulator>`_.
2019-01-24 01:43:25 +00:00
.. important::
2019-07-11 15:27:57 +00:00
**Building the compiler itself:** (*Only needed if you have not downloaded a pre-built 'fat-jar'*)
2019-01-24 01:43:25 +00:00
2020-03-14 14:19:03 +00:00
(Re)building the compiler itself requires a recent Kotlin SDK.
The compiler is developed using `IntelliJ IDEA <https://www.jetbrains.com/idea/>`_ ,
but only a Kotlin SDK installation should work as well, because the gradle tool is
used to compile everything from the commandline.
2020-03-14 14:19:03 +00:00
Instructions on how to obtain a prebuilt compiler are in :ref:`building_compiler`.
2018-08-06 01:35:43 +00:00
.. toctree::
:maxdepth: 2
:caption: Contents of this manual:
targetsystem.rst
2018-08-06 23:23:34 +00:00
building.rst
2018-08-06 01:35:43 +00:00
programming.rst
syntaxreference.rst
libraries.rst
2018-08-06 01:35:43 +00:00
todo.rst
Index
=====
* :ref:`genindex`