prog8/docs/source/index.rst

207 lines
7.1 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>`_ /
`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
Code examples
-------------
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
%import c64utils
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
ubyte candidate_prime = 2
2019-01-24 01:43:25 +00:00
sub start() {
2019-04-12 20:34:43 +00:00
memset(sieve, 256, false)
c64scr.print("prime numbers up to 255:\n\n")
ubyte amount=0
while true {
ubyte prime = find_next_prime()
if prime==0
break
c64scr.print_ub(prime)
c64scr.print(", ")
amount++
}
c64.CHROUT('\n')
c64scr.print("number of primes (expected 54): ")
c64scr.print_ub(amount)
c64.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
return 0
}
sieve[candidate_prime] = true
uword multiple = candidate_prime
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
The following programs shows a use of the high level ``struct`` type::
%import c64utils
%zeropage basicsafe
2019-07-29 21:11:13 +00:00
main {
struct Color {
ubyte red
ubyte green
ubyte blue
}
sub start() {
Color purple = {255, 0, 255}
Color other
other = purple
other.red /= 2
other.green = 10 + other.green / 2
other.blue = 99
c64scr.print_ub(other.red)
c64.CHROUT(',')
c64scr.print_ub(other.green)
c64.CHROUT(',')
c64scr.print_ub(other.blue)
c64.CHROUT('\n')
}
}
when compiled and ran, it prints ``127,10,99`` on the screen.
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.
2019-01-24 01:43:25 +00:00
- Usable on most operating systems.
2018-08-06 01:35:43 +00:00
- Based on simple and familiar imperative structured programming paradigm.
2019-01-24 01:43:25 +00:00
- 'One statement per line' code style, resulting in clear readable programs.
2018-09-01 17:28:11 +00:00
- Modular programming and scoping via modules, code blocks, and subroutines.
2018-08-06 01:35:43 +00:00
- Provide high level programming constructs but stay close to the metal;
still able to directly use memory addresses, CPU registers and ROM subroutines,
and inline assembly to have full control when every cycle or byte matters
2019-01-24 01:43:25 +00:00
- Arbitrary number of subroutine parameters (constrained only by available memory)
- Complex nested expressions are possible
- Values are typed. Types supported include signed and unsigned bytes and words, arrays, strings and floats.
- 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
2018-08-06 01:35:43 +00:00
the compiled program in an emulator and provide debugging information to the emulator.
2019-01-24 01:43:25 +00:00
- The compiler outputs a regular 6502 assembly source code file, but doesn't assemble this itself.
The (separate) '64tass' cross-assembler tool is used for that.
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.
- The compiler tries to optimize the program and generated code, but hand-tuning of the
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.
2019-08-14 20:28:44 +00:00
- There are many built-in functions such as ``sin``, ``cos``, ``rnd``, ``abs``, ``min``, ``max``, ``sqrt``, ``msb``, ``rol``, ``ror``, ``swap``, ``memset``, ``memcopy``
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.
A recent .exe version of this tool for Windows can be obtained from my `clone <https://github.com/irmen/64tass/releases>`_ of this project.
For other platforms it is very easy to compile it yourself (make ; make install).
A **Java runtime (jre or jdk), version 8 or newer** is required to run the packaged compiler.
2019-02-03 21:23:17 +00:00
If you're scared of Oracle's licensing terms, most Linux distributions ship OpenJDK instead
and for Windows it's possible to get that as well. Check out `AdoptOpenJDK <https://adoptopenjdk.net/>`_ for
downloads.
2019-01-24 01:43:25 +00:00
2019-02-03 21:23:17 +00:00
Finally: a **C-64 emulator** (or a real C-64 ofcourse) to run the programs on. The compiler assumes the presence
2019-01-24 01:43:25 +00:00
of the `Vice emulator <http://vice-emu.sourceforge.net/>`_.
.. 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
(re)building the compiler itself requires a recent Kotlin SDK.
2019-01-24 01:43:25 +00:00
The compiler is developed using the `IntelliJ IDEA <https://www.jetbrains.com/idea/>`_
IDE from Jetbrains, with the Kotlin plugin (free community edition of this IDE is available).
But a bare Kotlin SDK installation should work just as well.
2019-07-12 18:31:18 +00:00
Instructions on how to obtain a working 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
todo.rst
Index
=====
* :ref:`genindex`