RUN dot command with PATH search for launching programs

Discuss game and other programming topics not specifically covered in another forum

Moderator: Programming Moderators

Post Reply
Alcoholics Anonymous
Posts: 508
Joined: Mon May 29, 2017 7:00 pm

RUN dot command with PATH search for launching programs

Post by Alcoholics Anonymous » Sat Jul 07, 2018 5:19 pm

What Is It?

This new .run dot command works like the command line equivalent of NextOS's file browser. From a basic prompt, it will automatically locate and load a program by searching directories kept in an environment PATH variable. It can also be used to locate files found in the PATH and change to their directories so you can work on them there.

The currently supported file formats are:
tap, sna, snx, z80, o, p, nex

It's mostly written in c with some asm mixed in. Full source is available here: ... ommand/run


The last compiled executable is "RUN" located in the link above. A direct link for downloading is here: ... nd/run/RUN

Copy this RUN command into /bin on your sd card or mmc image for emulators.

You will also have to define a PATH environment variable to indicate which directories you want searched. There is another forum posting about environment variables here: viewtopic.php?f=13&t=1229

In short, create a text file "/sys/env.cfg" on the sd card or mmc image if you don't have one already. You might have to create the /sys directory if it doesn't exist already. This is where the system's global environment variables will be held. The file contains "name = value" pairs that programs can read to locate values set by the user. Right now we're going to define a PATH variable the .run will look up to find out which directories it should look for programs in.

Add to the file something like:

PATH = /demos/*;/games;/games/*;/games/zx81/*

This must be all in one line no matter how long the PATH gets. This particular set of search paths makes sense for the sd card contents I have but you should modify it depending on what your directory structure looks like.

The code that parses the environment file is robust and so is the code that reads the PATH variables. You can have weird formatting, errors in the env file and it will still work. The directories listed in PATH can be separated either by ; or :. You can use \ instead of / (internally \ is changed to /). Long names with embedded spaces are ok.

Special treatment is applied to directories ending in "/*". This indicates that all directories contained in the indicated directories should be searched. So, eg, "/games/*" means look in all directories contained in "/games". Note that it doesn't mean look in "/games" as well and that's why there is a separate "/games" entry in the PATH above.

"env.cfg" should be saved with unix line endings "\n" and most text editors have an option to do that. However, it should also work with windows line endings "\r\n" but this hasn't been tested.


You've copied RUN to /bin, you've created a PATH in /sys/env.cfg. Now you're ready to go.

These are some examples to familiarize you with common usage. From basic do the following:

Prints usage information

.run -p
Prints all directories that will be searched. An X indicates the directory does not exist.

.run -? castlevania.tap
Lists all directories the file "castlevania.tap" is located in (the current directory is not searched unless it's part of PATH). Of course there can be more than one "castlevania.tap" and each instance will be numbered to distinguish them.

.run -c castlevania.tap
Look in the current directory then in PATH directories for the first instance of "castlevania.tap" and change to its directory. A ".ls" will show you're in the same directory as "castlevania.tap".

.run -c -3 castlevania.tap
Recall there can be many "castlevania.tap" stored in different directories. The "-?" option listed them all and numbered them. Here "-3" means choose the third instance of "castlevania.tap".

.run -c mytext.txt
.run can locate any file you may have been working on. This one will change to the directory containing "mytext.txt" if you forgot where you placed it. I forthcoming "FIND" dot command will do this better.

.run castlevania.tap
Look in the current directory then in PATH directories for the first instance of "castlevania.tap" and mount the tap file. The directory will be changed to "castlevania.tap"'s location. To run - LOAD "t:": LOAD ""

.run -r castlevania.tap
Same as above but don't change directory to "castlevania.tap"'s location.

.run warhawk.sna
Look in the current directory then in PATH directories for the first instance of "warhawk.sna" and run it. Only tape files require an extra step to run; other file types will just start.

.run 3dmonstermaze.p
It works for zx81 snapshots too.


The browser is pretty good for loading and launching files. However some people may prefer to use the command line or start something from basic. Because PATHs are searched automatically you don't even have to find the file as .run will find it for you.

Post Reply