Skip to content

Start here

This page takes you from nothing to a running d/BASIC program in a couple of minutes. You will print a line in the browser, play a small guessing game, mix old-style line numbers with modern labels, and open your first window. By the end you will know the two kinds of program d/BASIC can be, and which chapter to read next.

d/BASIC is the BASIC of d/OS, the operating system that brings modern software to 8-bit home computers such as the Atari 800, the Commodore 64 and the Apple II. It also runs in your browser and on your desktop. It is easy to start because the first step is genuinely small. Print something. Add a variable. Add a decision. Only then decide whether you need procedures, objects, or a window.

First contact

Open the browser playground, replace whatever is in the editor with this, and choose Run:

10 PRINT "HELLO"
20 PRINT "THE MACHINE IS LISTENING."
30 END

Those numbers are real line numbers, not comments. A jump can land on one. But they are optional, and this is the same program without them:

PRINT "HELLO"
PRINT "THE MACHINE IS LISTENING."
END

Both of these are console programs: PRINT, INPUT, and the program's final status all live in a text console. The same kind of program also works as a quiet script that another program runs for you; Console, Scripts & GUI explains the difference.

A program with a little life in it

Now let the program ask you something and decide what to say back.

DEFINT A-Z

DIM Secret, Guess
Secret = 7

PRINT "I AM THINKING OF A NUMBER FROM 1 TO 10."
INPUT "YOUR GUESS"; Guess

IF Guess = Secret THEN
  PRINT "EXACTLY RIGHT."
ELSEIF Guess < Secret THEN
  PRINT "TOO LOW."
ELSE
  PRINT "TOO HIGH."
END IF

DEFINT A-Z says that any name beginning with a letter from A to Z is an INTEGER unless you declare otherwise. It is a compact way to say that your counters and small whole numbers really are whole numbers.

INPUT waits for you

In the playground, an answer row appears under the question; type a number and press Enter. On the desktop, the d/OS runtime (the program that runs your compiled code) reads the reply from the terminal. When a script runs with no input line left, the program stops at the normal end of input and says so, rather than guessing an answer.

Numbered lines and named labels can mix

Bringing an old listing forward does not mean rewriting all of it. Modernize the parts you touch and leave the rest alone.

10 GOSUB Banner
20 FOR Turn% = 1 TO 3
30   PRINT "TURN"; Turn%
40 NEXT Turn%
50 GOTO Finished

Banner:
  PRINT "MIXED-ERA BASIC, ONE PROGRAM"
  RETURN

Finished:
  PRINT "DONE"

A jump target can be a line number or a named label. You can put several statements on one line separated by :, but one statement per line is easier to read and easier to debug.

The other kind of program: a window

A window program does not run from top to bottom. Instead it defines handlers that the system calls at the right moments. Three are fundamental: open, draw, and close. A program with handlers is a window program, and dbasic run opens a window for it. A program with only ordinary top-level statements is a console program. d/OS calls these the program's two faces, and one compiled program file, .dbc, carries whichever faces the source declares.

WINDOW SUB OPEN()
  SERVICE SET_TITLE("First window")
  SERVICE INVALIDATE()
END SUB

WINDOW SUB DRAW()
  INTENT GFX.BEGIN_FRAME()
  INTENT GFX.FILL_RECT(0, 0, 320, 192, 2081)
  INTENT GFX.DRAW_TEXT(12, 14, "HELLO, WINDOW", 3, -1, 2081)
  INTENT GFX.PRESENT()
END SUB

WINDOW SUB CLOSE()
END SUB

The source says what to draw. Each INTENT line is an intent: a named request such as "fill this rectangle" that the machine carries out however it can. The host decides how the frame reaches a browser canvas, a desktop window, or a d/OS screen. That separation is the heart of what makes a d/BASIC program portable.

Read Windows & Events before you add keyboard and mouse input. Read Widgets when you would rather use a ready-made button than paint one from rectangles.

Desktop command line

The dbasic command-line tool uses the same compiler and the same runtime as the playground:

dbasic run hello.bas
dbasic build hello.bas -o hello.dbc
dbasic exec hello.dbc

A window program (one with handlers) opens its native window on its own with the same run. A console program that paints with GFX intents can be given a window to paint in:

dbasic run --native app.bas

run accepts either source or a compiled program file and tells which is which from the file's bytes. build produces a .dbc you can carry anywhere; exec runs one you already built. See Bytecode & Delivery for delivering to Windows, Linux, macOS, the browser, and d/OS.

The applications

The kit's apps/ folder has the five d/BASIC applications as compiled programs you can run right away: Calculator, d/Calc (a spreadsheet), d/Write (a document editor), Cantor (a 1-bit adventure), and Star Commander (a space-combat game). Calculator, d/Calc, and d/Write come with their full source, which makes them the largest d/Works examples you have; the two games ship as programs only. The kit's README has the launch line for each; the two document apps take a --data-mount folder for what they save, and Cantor a --file-mount folder for its pictures and sound.

Visual Studio Code

The download page also has a VS Code extension, dbasic-0.1.0.vsix: highlighting, error markers as you type, formatting, go-to-definition, rename, hover help, completion, and Build/Run/Trace from the command palette. Install it from the file (Command Palette, then Extensions: Install from VSIX...) and set dbasic.server.path to the kit's bin/dbasic (bin\dbasic.exe on Windows), or put that bin folder on your PATH. The extension has no parser of its own: the compiler is the language server, so what the editor says is exactly what build says. One file works on macOS, Windows, and Linux.

How to read compiler messages

A good message answers three questions:

  • Where? A source line and column.
  • What? An ordinary syntax or type problem, or a deliberate stop.
  • Why? A plain explanation, often with an error code.

When the compiler or the runtime says it declined, do not read that as a crash. It means d/BASIC reached a boundary on purpose (for example a request the host cannot carry out, a library that does not match, or a machine operation that is never allowed) and stopped and told you exactly what is missing, instead of pretending the request worked.

Choose your next chapter

Next: Console, Scripts & GUI →