sejo
/
compudanzas
2
3
Fork 3
Code Issues Pull Requests Projects Releases Wiki Activity

new intro including the launcher

This commit is contained in:
sejo 2022-11-13 15:34:35 +01:00
parent d74942e0e5
commit 42a0eafec8
1 changed files with 99 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

146
src/uxn_tutorial_day_1.gmo
View File

@ -154,62 +154,57 @@ the instruction will normally imply a change in the stack(s), and sometimes it m
# installation and toolchain
## local install
## desktop bundles
in order to run varvara locally and off the grid, we'd have to get the uxn assembler (uxnasm) and emulator (uxnemu) from their git repository:
in order to run varvara locally and off the grid we need to get an appropriate emulator.
=> https://git.sr.ht/~rabbits/uxn ~rabbits/uxn - sourcehut git
the 100R website allows you to download the emulators for major desktop systems; these come bundled with a selection of program in the form of "roms":
you can either build these tools from source, or download pre-compiled binaries for multiple platforms.
=> https://100r.co/site/uxn.html 100R — uxn
you can find the installation instructions in the repository.
if you need a hand, find us in #uxn on the fediverse :)
=> https://merveilles.town/tags/uxn #uxn in merveilles
### using the toolchain
you'll see that when building or downloading uxn, you will get three executable files:
* uxnemu: the emulator
* uxnasm: the assembler
* uxncli: a non-interactive console-based emulator
in principle you can double click uxnemu and have it run.
however, we'll use these programs from the command line.
the idea is that in order to run a program written in uxntal, the uxn assembly language, first you have to assemble it into a "rom" with uxnasm. then you can run this rom with uxnemu.
for example, in order to assemble and run {darena} that is in projects/examples/old/ :
assemble:
depending on your system, you might be able to launch the emulator (uxnemu) with a double-click, or you might need to use a console to navigate to its location and run it:
```
$ ./uxnasm darena.tal darena.rom
$ ./uxnemu
```
run:
that's it! you will be greeted by a screen corresponding to the launcher rom.
```
$ ./uxnemu darena.rom
```
take a look at the available demos! (or not, and let's start programming ours!)
from there you will be able to run the other roms by clicking them, pressing Enter, or the Ctrl key. you can go back to the launcher by pressing the F4 key.
### uxnemu controls
these are the controls you can use within uxnemu, regardless of the rom that you are running:
* F1 circles between different zoom levels
* F2 shows the on-screen debugger
* F2 toggles the debugger
* F3 takes a screenshot of the window
* F4 loads a launcher.rom that lets you browse and open roms in the current directory
* F4 loads the launcher.rom that lets you browse and open roms in the current directory
## learn-uxn site
## building from source
alternatively, you can try and experiment with all the materials in the tutorial with the learn-uxn site by metasyn:
alternatively, you can get the sources from the uxn git repository, where you will also find the building and installation instructions:
=> https://git.sr.ht/~rabbits/uxn ~rabbits/uxn - sourcehut git
## online: learn-uxn site
finally, you can try and experiment with all the materials in the tutorial with the learn-uxn site by metasyn:
=> https://metasyn.github.io/learn-uxn/ learn-uxn by metasyn
## the toolchain
depending on your system, you might see that besides uxnemu there are a couple of other programs, uxnasm and uxncli.
* uxnemu is the full-featured emulator
* uxncli is a console-based emulator
* uxnasm is an uxntal assembler
during this journey we will be writing our programs in uxntal, the assembly language for uxn machines.
these programs will have to be assembled in order to become roms that we will be able to run with an emulator.
# uxntal and a very basic hello world
uxntal is the assembly language for uxn machines.
@ -238,14 +233,69 @@ note that the order of the operands in the subtraction is similar to the order f
## a first program
let's write the following program in our favorite text editor, and save it as hello.tal:
### using left and the launcher
uxn and the tools that have been built around it allow us to learn and develop completely within the system.
for instance, when you run the emulator you will see that you can open a program called left: a text editor!
=> https://100r.co/site/left.html 100R — left
open it, as we will write our first program there!
first of all, rename the file you are working on. you can use the visual menu or press Ctrl + r, then delete the current filename, replace it with hello.tal, and press Enter to confirm.
now write the following program:
```
( hello.tal )
|0100 LIT 68 LIT 18 DEO
```
save it, and then let's assemble it and run it:
save it using the visual menu or Ctrl + s, and then go back to the launcher by pressing F4.
you will see now that the listing in the launcher includes your newly created file, hello.tal!
note that this is a text file only, and it's not a rom yet. however, the launcher makes it very easy to convert it to a rom, or more precisely, to assemble it!
just click the hello.tal, or use the arrow keys to reach it and then press Enter or Ctrl: if everything went alright you will see that a hello.tal.rom file appears!
additionally, note that the accompanying console will print something like:
```
on-reset 0x0000
0x0004 lines of source code.
0x002e bytes of heap used, 0xa34e bytes free.
```
if there are errors during assembly, you will see them there.
now that you have hello.tal.rom you can run it from the launcher as any other rom!
when you run it you will see that the screen will be cleared and that the console will show the output of our program:
```
h
```
interesting, what is happening?
i invite you to try replacing the 68 in the code with, for example, 65.
to do that you'll have to open left again, rename the file to hello.tal so that it opens it, modify the file, save it, return to the launcher, assemble, and then run again!
### using another text editor and uxn tools
alternatively, you can use your favorite text editor and the uxn programs to replicate what we just did from within uxnemu.
you can write hello.tal using your text editor, and then save it along the other files bundled with the emulator:
```
( hello.tal )
|0100 LIT 68 LIT 18 DEO
```
once you have the file, we can assemble and run it from the console:
```
$ ./uxnasm hello.tal hello.rom && ./uxnemu hello.rom
@ -254,26 +304,28 @@ $ ./uxnasm hello.tal hello.rom && ./uxnemu hello.rom
a black window will open, and in the console we will see an output that looks like the following:
```
Assembled bin/hola.rom in 5 bytes(0.40% used), 0 labels, 0 macros.
Assembled hello.rom in 5 bytes(0.01% used), 0 labels, 0 macros.
Loaded hello.rom
h
```
the last 'h' we see is the output of our program.
as we saw in the previous case, the last 'h' we see is the output of our program.
edit the code changing the 68 to, for example, 65, and now you'll see an 'e'.
feel free to use any of these approaches, either working completely from within uxnemu, or using your own tools and the uxn programs.
interesting! so what is happening?
everything that follows in this journey regarding uxntal is completely agnostic to the tooling you use!
## one instruction at a time
we just ran the following program in uxntal:
we just ran the following program written in uxntal:
```
( hello.tal )
|0100 LIT 68 LIT 18 DEO
```
now let's analyze it!
the first line is a comment: comments are enclosed between parenthesis and there have to be spaces in between them. similar to other programming languages, comments are ignored by the assembler.
the second line has several things going on:
@ -306,9 +358,9 @@ you can see the hexadecimal values of the ascii characters in the following tabl
=> https://wiki.xxiivv.com/site/ascii.html ascii table
### literal numbers
### raw numbers
note that the literal numbers that we wrote, 0100, 18 and 68, are written in hexadecimal using either 4 digits corresponding to two bytes, or 2 digits corresponding to one byte.
note that the raw numbers that we wrote, 0100, 18 and 68, are written in hexadecimal using either 4 digits corresponding to two bytes, or 2 digits corresponding to one byte.
in uxntal we can only write numbers that are 2 or 4 hexadecimal digits long. if, for example, we were only interested in writing a single hexadecimal digit, we would have to include a 0 at its left.
@ -362,7 +414,7 @@ we could expand our program to print more characters:
LIT 0a LIT 18 DEO ( newline )
```
if we assemble and run it, we'll now have a 'hello' in our terminal, using 30 bytes of program :)
if we assemble and run it, we'll now have a 'hello' in our console, using 30 bytes of program :)
ok, so... do you like it? does it look straightforward? maybe unnecessarily complex?