Manual · 1

Getting started

This page takes you from installing VCSIDE to a first program running in an emulator, and explains the project file and the panels you will see.

Install

VCSIDE is a single program. On macOS it is VCSIDE.app; on Windows and Linux it is vcside (or vcside.exe) with its data/ folder next to it. It needs OpenGL 2.1 or later and nothing else of its own.

It does not include the assemblers and emulators. It looks for them in your PATH and in the usual install folders, and you can set any of them by hand in Settings → Tools (Cmd+,).

You don't have to install everything before starting. Before building or running, VCSIDE checks what the project needs. If something is missing, a window says what it is and how to install it, with its official download page, Choose the file... and Search again, and then carries on with the build.

A first project

When nothing is open, VCSIDE shows its welcome page: New project, Open project, Open folder and the recent projects and folders, one click away.

Use New project (also in File). Give it a name and a folder, and choose:

• Language of the project: assembly (DASM), batari Basic, or C for ELF cartridges.
• TV standard: the ones the language can build for, among NTSC, PAL and the others the emulators know. The assembly template sets its line counts for 60 or 50 Hz, and a batari Basic one for PAL gets set tv pal. Multiple (in the code) is for a program that handles several systems itself: the assembly template then chooses with -DPAL=1.
• Start from: an empty project, or an example. For assembly and for C, the example is an animated sprite drawn in the graphics editor that walks with the joystick.

Then press F5. VCSIDE builds the program and opens it in the emulator.

The project file

A folder without one builds too: open it with File → Open folder... and press F7. VCSIDE recognises a Makefile or build script, a DASM source with its processor line or a batari Basic one (in the folder or in src/), shows what it found and builds it as it is, or writes the project file first if you want to keep or change the settings.

A project is a .vcsproj file, plain JSON that you can keep under version control. Build → Project settings..., or a click on the .vcsproj in the project panel, opens it in a tab as a form or as text, with a switch between both. Keys VCSIDE doesn't use are kept.

{
  "name": "walker",
  "language": "dasm",
  "main": "main.asm",
  "output": "build/walker.bin",
  "format": "4K",
  "tv": "NTSC",
  "emulator": "gopher2600",
  "illegal_opcodes": "allow",
  "include_dirs": []
}

The format, TV standard, emulator and illegal-opcode policy can also be changed in the Build menu.

Breakpoints, the files that were open and where the cursor was are kept apart, in <project>.vcsproj.user. Add it to .gitignore if you don't want to share them.

Opening a folder that has a Makefile or a build script and no project file offers to create one, with the main source and the ROM read from the folder.

The window

The panels can be moved and docked wherever you like:

Project

All the project's files, hidden ones too. What Git ignores, and the build folder, show dimmed. Double-click to open one.

Editors

One tab per open file: code, graphics (.vcsgfx), project settings, or a PNG or BMP image.

Output

What the build and the emulator print.

Problems

Errors and warnings from the build and the space report. Click one to open its line.

Space

The space report of the last build.

Documentation

The knowledge base, which follows F1.

On macOS the menus are in the system menu bar, and the application menu has About, Tools and Language. On Windows and Linux they are in the window. Esc closes any dialog.

Images open in a viewer with sharp pixels: a click zooms in, Alt+click or the right button zooms out, the wheel zooms where the pointer is and dragging moves the image. The bottom line gives the pixel under the pointer and its colour, and the view follows the file when it changes on disk.

View zooms the whole IDE, and the fonts are drawn again at each size so they stay sharp. Shortcuts go by the character of the key, so they work with any keyboard layout: Ctrl+/ is Ctrl+Shift+7 on a Spanish keyboard.

Windows and sessions

Each window has one project. File → New window opens another one on the welcome page, Close project takes a window back to it, and opening a project that is already open in another window brings that window forward. Settings such as the theme, the zoom and the recent projects are shared by all.

When you quit VCSIDE it remembers its windows: next time each one opens again with its project, in the same place and size, with the files that were open, the cursor where it was in each and the breakpoints. If you start it with a file or folder to open, it opens just that.

Keyboard shortcuts

On macOS every Ctrl below is Cmd.

These are the macOS keys; on Windows and Linux, Cmd is Ctrl and Option is Alt. On a Mac laptop the F keys may need Fn.