If you haven't done yet, install all the necessary tools first.
Your First Project
Open a terminal and change to the directory where your copy of The Next Skeleton is located. There is a tool called
nxtsetup that will create a skeleton for your project. Just invoke it, passing the target directory and your project name as parameters. Say we want to create a project called "helloworld" in the "projects" directory of your home directory:
./nxtsetup --dir ~/projects helloworld cd ~/projects/helloworld
That's all! Your project is ready to be started. Just type:
It will take a while at the first time, so please be a little patient.
After a couple of seconds, an emulator window appears, and your program is started automatically. You should see a black window now, and a famous text that reads:
Congratulations! With three commands only, you have created a new project, assembled it, and started it on a ZX Spectrum Next emulator.
You can now close the emulator window. Open the
src/helloworld.asm file in your favourite editor, and change it a bit (just change the message text if you're worried to break something). After that, invoke
ant run again. This time, the emulator starts almost instantly, and is showing your change.
Basically, that's all you need to know. You can now start to modify the
helloworld.nex file, add other files, and experiment with the setup.
As soon as you want to know more about the how the skeleton works, have a look at the text below, and read the other chapters of this documentation.
The tool has created a project skeleton at
~/projects/helloworld. Let's have a look at the files in this directory:
src/helloworld.asm– This is a simple assembler program. It serves as a starting point for your own project. It is expected to have the same name as your project, followed by an
.asmsuffix. Do not rename or delete this file, otherwise your project cannot be built any more.
resourcesdirectory contains static files that are supposed to be copied to the SD card. This
readme.txtis just an example file. You can safely delete it, or the entire directory, if you won't need it.
build.xml– This is the
antbuild file. It contains all the steps that need to be done in order to assemble and run your program.
tools/– This directory contains some helper tools for building the project. You can ignore it, as you won't have to change the files in there anyway. However, you must not delete this directory, otherwise your project cannot be built any more.
dist/– This directory wasn't there when you created the project, but was created when you ran
ant. It contains all the files that are made when you build your project. You can safely delete this directory if you want to.
antwill then recreate it on the next run.
.image/– This directory has been created by
antas well. It contains an unpacked version of the ZX Spectrum Next distribution. You can delete this directory at any time. If
antfinds it missing, it will download and unpack the distribution again. However, do not change anything in this directory, as the changes are not permanent and may become reverted.
.gitignore– This file keeps git from adding the
.imagedirectories. Their content is generated and consume a lot of space, so there is no need (and no real purpose) to commit them to an SCM. If you won't use git, you can delete this file.
Behind the Curtain
In the background,
ant did a lot of work for you. The
build.xml file contains all the steps that are necessary to manage your project. They are called targets.
run is such a target. It depends on other targets to be executed before.
ant takes care for that, too.
This is what
ant actually did when you invoked it for the first time:
It found out that the
.imagedirectory was missing, so it downloaded an official distribution file from zxspectrumnext.online, created the
.imagedirectory, and unpacked the distribution there. These files are necessary for creating an MMC image, and for running the #CSpect emulator. There is no need for you to take care of that, though.
antdoes all the heavy lifting.
It found out that the
distdirectory was missing, so it was created.
It assembled the
src/helloworld.asmfile. The assembler created a file
helloworld.nexthat was written into the
distdirectory. This is your program! You could copy this
.nexfile to your ZX Spectum Next's SD card and run it on the real machine.
It found out that there was no MMC image file yet, so it created a file
dist/image.mmc, formatted it, and copied the contents of the
.imagedirectory to it. This
dist/image.mmcfile is used by the emulator later. If you delete it,
antwill create a new one.
As a preparation,
antmade a directory
helloworldon the freshly created MMC image. It then copied your program and all the files in the
resourcesdirectory to that directory.
Finally, the emulator was started.
autoexec.basfile that immediately loads your program as soon as the Spectrum Next has booted up. Then the #CSpect emulator was started, using the
dist/image.mmcfile as MMC image.
So a lot of things have happened automatically after you typed
ant run for the first time.
If you invoke
ant run again, it finds the
.image directory to be present, so it will only need to invoke the assembler, and then immediately start the emulator. This is why the first run is taking a lot of time, while the subsequent runs are much faster.