BlitzMax

BlitzMax

  • Downloads
  • Docs
  • API
  • Resources
  • About

›Tools

Setup

  • Getting Started
  • Win32
  • Linux
  • macOS
  • Android
  • iOS
  • Raspberry Pi
  • NX (Switch Homebrew)
  • Custom Settings

Tutorials

  • Beginners Guide
  • OOP Tutorial
  • Network Programming
  • TCP Socket Programming

Language

  • Arrays
  • Basic Compatibility
  • Collections
  • Comments
  • Conditional Compiling
  • Constants
  • Data Types
  • Debugging
  • Enums
  • Exceptions
  • Expressions
  • Functions
  • Identifiers
  • Literals
  • Modules
  • Objects
  • Program Flow
  • Slices
  • Strings
  • User Defined Types
  • Variables
  • Advanced Topics

    • Interfacing With C
    • Memory Management
    • Pointers
    • Custom Pre/Post Compilation Scripts
    • Creating DLLs

Tools

  • MaxIDE
  • BlitzMax Make (bmk)
  • BlitzMax Compiler (bcc)
Edit

MaxIDE

MaxIDE is the code editor that ships with BlitzMax.

IDE stands for Integrated Development Environment, and while MaxIDE may not be quite the IDE you might be used to using if you've spent time with other programming languages (like Java or C#), it generally is adequate for day-to-day coding in BlitzMax.

Using MaxIDE

All the various options for building your applications are available via the drop-down menus, with a set of common actions also present on the toolbar strip above the main editing area.

The right-hand navigator panel provides access to the help, your projects, the structure of the currently edited BlitzMax source, and the debug stack.

Editing

To start editing, you can either open an existing source file, or create a new one.

To create new file, select New (Ctrl-N or ⌘-N) from either the Menu or the Toolbar. This creates a new, Untitled, editor for you.

When it's time to save your hard work, you can select Save (Ctrl-S or ⌘-S) from either the Menu or the Toolbar. For Untitled files, you will also be prompted to specify a location and a new name for your source.

Untitled files are, by default, BlitzMax (.bmx) source files. Before you start editing, if you plan on using the source file with a different extension and you have syntax-highlighting enabled, it's recommended that you save it first with the new filename, then Close (Ctrl-W or ⌘-W) and Open (Ctrl-O or ⌘-O) it again - otherwise MaxIDE will apply formatting to any BlitzMax keywords you might use.

Quick Menu

If you click on the right mouse button (or Ctrl-Click the mouse on macOS) whilst editing, the Quick Menu will pop up...

OptionDescription
Quick HelpProvides a brief summary about the keyword currently under the cursor.
Choosing this again on the same word will open up the Help page for more details.
CutCuts the current selection into the clipboard.
CopyCopies the current selection into the clipboard.
PastePastes the contents of the clipboard to the current cursor location.
Select AllSelects the whole text of the current file.
Block IndentBlock indents the current line or lines.
Block OutdentBlock outdents the current line or lines.
FindOpens the Find dialog.
Find NextFinds the next matching text from the current cursor location.
ReplaceOpens the Find and Replace dialog.
Goto LineOpens the Goto Line dialog.

Building and Running

There are two primary build modes - Debug and Release. With a Debug build, BlitzMax creates extra support and information about your application that allows MaxIDE to control the execution of the application and examine the contents of variables during the run. In Release mode, all this extra information is removed, resulting in smaller and faster application.

Let's create a simple application and take a quick look at working in MaxIDE.

First, select New from the File Menu or toolbar. This will create a new, empty source file for you to work with.

Enter the following text :

'
' My first BlitzMax program
'
Print "Hello World!"

Now, it's time to build and run: Select Build And Run from the Program Menu or click on the powered Rocket icon in the toolbar.

The view will switch from your source file to the Output tab, and you should see the following output:

Building untitled1
[ 23%] Processing:untitled1.bmx
[ 86%] Compiling:untitled1.bmx.console.debug.win32.x64.c
[100%] Linking:untitled1.debug.exe
Executing:untitled1.debug.exe
Hello World!

Process complete

The very first time you build for a particular architecture, you may see a lot of compiler output before the build completes. This is because BlitzMax is also having to build the required modules for your application too. On subsequent builds, it won't need to do this, and the output, and build time, will be far shorter.

Errors

When BlitzMax encounters an error, a dialog window will uaually appear with a brief summary of what occurred.

For example, let's create a new program with an error, and attempt to build it :

'
' My first bug!
'
rint "Hello World!" 'oops! Forgot a 'p'!

This program has an error in it - there is no such command as rint so attempting to build this program will produce the following error:

Error dialog

When you close the error dialog and return to the source code window, the cursor will be placed at the line containing the error, allowing you to fix it.

This type of error is known as a compile time error, because the bug was detected by the compiler before you actually ran the program.

Debugging

The compiler, however, cannot catch all possible errors - some errors are not apparent until your program is run. These kinds of errors are known as runtime errors.

Here's an example of a program with a runtime error in it:

'
' My first runtime bug!
'
Local an_array[10]

For Local k=0 To 10
    Print an_array[k]
Next

If you run this example, you should see the following error message: Runtime error dialog

Note how the pane on the right has also switched to the Debug pane. This means your program is in debug mode, and by navigating through the debug pane you can inspect your programs variables.

In this particular example, on examining the variable contents, you'll find that the variable k has the value 10. In BlitzMax, arrays start counting cells from 0 rather than 1, so the last entry of an array of size 10, is actually at index 9.

Stepping Through Your Code

MaxIDE also allows you to step through the statements of your running application in Debug mode. To do this, you need to add a special command in your source called DebugStop.

Here's an example of a program ready to be debugged:

'
' My first debugging session
'
Local total = 0

DebugStop
For Local k=0 Until 10
    total :+ (k * k)
Next

Note the line with the DebugStop command. When you run the program in Debug mode, execution will stop at this command, the current line will be highlighted in the editor, the Debug pane on the right will open, and MaxIDE will wait for you to interact with it.

You have several options at this point. Clicking on the green Continue icon in the toolbar will cause MaxIDE to resume running the program.

Using Step Over will execute the next statement. If the statement is a function call, for example, stepping over will run the code in the function and the next line after returning from the function will be highlighted.

If you use Step In on a function call, the first line inside the function will be highlighted, and you can then step through each line of the function.

Whilst stepping, the Debug panel will show the values of all of the variables in the current scope, as well as those variables in scope down the call stack. You can example the call stack by opening the individual listed functions in the Debug pane.

Toolbar

Toolbar buttons

ButtonActionDescription
NewCreates a new Untitled BlitzMax (.bmx) source file.
OpenOpens an existing file.
CloseCloses the current editor tab.
SaveSaves the current file.
CutCuts the current selection into the clipboard.
CopyCopies the current selection into the clipboard.
PastePastes the contents of the clipboard to the current cursor location.
FindOpens the Find dialog.
BuildBuilds the current source file (or locked build file).
/ Build & Run / ContinueBuilds and runs the current source file (or locked build file).
In debug mode while stopped, continues the program from the next statement.
StepIn debug mode, steps over the next program statement.
Step InIn debug mode, steps into the next program statement.
Step OutIn debug mode, steps out of the current block or function.
TerminateStops the current build or program run.
HomeOpens the documentation Home page.
BackNavigates to the previous documenation page.
ForwardNavigates to the next documentation page.

The Menus

File Menu

Menu OptionKeyboard ShortcutDescription
NewCtrl-NCreates a new source file.
Open...Ctrl-OOpens an existing source file.
Open RecentReopens a recently used source file.
Close TabCtrl-WCloses current source file.
Close All TabsCtrl-Shift-WCloses all source files.
Close Other TabsAlt-Ctrl-WCloses all source files except the current.
SaveCtrl-SSaves current source file.
Save AsCtrl-Shift-SSaves current source file under a different name.
Save AllSaves all open source files.
Next TabAlt-RightSwitches to next open source file.
Previous TabAlt-LeftSwitches to previous open source file.
IDE OptionsOpens the IDE options panel.
Project ManagerOpens the project manager panel.
PrintCtrl-PPrints current source file.
ExitCloses down and exits the IDE.

Edit Menu

Menu OptionKeyboard ShortcutDescription
UndoCtrl-ZUndo most recent source file edit.
RedoCtrl-YRedo most recently undone source file edit.
CutCtrl-XCuts selected text from current source file.
CopyCtrl-CCopies selected text from current source file.
PasteCtrl-VPastes the contents of the clipboard to the cursor location in the current source file.
Select AllCtrl-ASelects all text in current source file.
Block IndentCtrl-[Indents the currently highlighted block.
Block OutdentCtrl-]Unindents the currently highlighted block.
Find...Ctrl-FFinds text in the current source file.
Find NextF3Finds the next occurrence of text.
ReplaceCtrl-HFinds and replaces text.
Goto Line...Ctrl-GGo to a line in the current source file.
Find in FilesCtrl-Shift-FSearch many files for an occurrence of text.

Program Menu

Menu OptionKeyboard ShortcutDescription
BuildBuilds the current source file (or locked build file).
Build and RunBuilds and runs the current source file (or locked build file).
Command LineSpecifies command line options for BlitzMax apps.
StepIn debug mode, steps over the next program statement.
Step InIn debug mode, steps into the next program statement.
Step OutIn debug mode, steps out of the current block or function.
TerminateStops current build or program run.
Build OptionsOpens the Build Options sub-menu.
App OptionsOpens the App Options sub-menu.
PlatformOpens the Platform sub-menu.
ArchitectureOpens the Architecture sub-menu.
App StubOpens the App Stub sub-menu.
Developer OptionsOpens the Developer Options sub-menu.
Lock Build FileLocks the current source file for future build and build and run operations.
This can be useful if you have a multi-file project and are editing several source files but only ever rebuilding one of them.
Unlock Build FileUnlocks the currently locked build file.
Build ModulesBuilds any recently modified modules.
Rebuild All ModulesRebuilds all modules from scratch.
Rebuild DocumentationRebuilds module documentation.

Build Options

Menu OptionDescription
Quick BuildEnable or disable quick builds. The quick build feature causes the compiler to only recompile modified files.
Debug BuildEnable or disable debug builds. Debug builds performing extra error checking at runtime, at the cost of some execution speed.
Quick ScanDon't scan modules for changes when building apps. This can improve compile times on some systems.
Overload WarningsProduces warnings about potential conversion problems with function arguments.
When disabled, the build will fail instead.
It is generally encouraged that you choose your own casting, in order to prevent loss of precision/data.

App Options

Menu OptionDescription
Build Console AppInstructs BlitzMax to build a lightweight, text-only application.
Build GUI AppInstructs BlitzMax to build a 'GUI' application.
Build Shared LibraryInstructs BlitzMax to build a DLL.

Platform

Contains plaftorm / operating system specific build options.

Menu OptionDescription
Win32Builds applications for Windows.
macOSBuilds applications for OS X. (available on macOS only)
iOSBuilds applications for iOS devices. (available on macOS only)
LinuxBuilds applications for Linux.
Raspberry PiBuilds applications for Raspberry Pi.
AndroidBuilds applications for Android devices.
NXBuilds applications for NX (Switch Homebrew).

Architecture

Contains architecture / processor specific build options. For example, you can use these options to build an application individually for 32-bit and 64-bit versions of Windows.

Menu OptionDescription
x86Creates x86 compatible application binaries.
x64Creates x64 compatible application binaries.
PPCCreates PPC compatible application binaries.
ArmCreates Arm compatible application binaries. (Raspberry Pi
ARMeabi v5Creates x86 compatible application binaries. (Android)
ARMeabi v7aCreates x86 compatible application binaries. (Android)
ARM64 v8aCreates x86 compatible application binaries. (Android)
ARMv7Creates x86 compatible application binaries. (iOS)
ARM64Creates x86 compatible application binaries. (iOS / NX)

App Stub

Menu OptionDescription
brl.appstubUses the built-in Appstub module.

Developer Options

Menu OptionDescription
Verbose BuildOutputs more information to console when building/compiling
GDB Debug GenerationGenerates GDB compatible debugging code, allowing BlitzMax source-level stepping in GDB.

Help Menu

Menu OptionKeyboard ShortcutDescription
HomeGoes to the help home page.
BackReturns to previous help page.
ForwardAdvances to the next help page.
Quick HelpF1Provides a brief summary about the keyword currently under the cursor.
Choosing this again on the same word will open up the Help page for more details.
About MaxIDEShows information about BlitzMax and the IDE.

Options

There are several options you can configure in MaxIDE, like fonts, colours and highlighting.

General Options

MaxIDE options

OptionDescription
Show toolbarWhen disabled, the toolbar strip is hidden.
Open Files at StartupWhether to re-open files that were open when MaxIDE was last closed.
Auto CapitalizeCauses keywords in the source file to match the capitalization of its declaration.
For example, if you type strict, this option will change it to Strict.
Syntax HighlightingWhether to apply colour and styling to BlitzMax (.bmx) source files.
Enable .bmx Bracket Matching
Auto BackupWhen enabled, a .bak copy of the file is generated when the source file is opened in MaxIDE.
Auto IndentWhen hitting return in the editor, the new line will start indented to the same level as the previous line.
Hide Output When Process CompleteHides the Output View once the program has finished.
Use External Help BrowserCauses documentation to be opened in the default browser, rather than switching to the Help tab in MaxIDE.
Use OS Specific Shortcut Keys
Sort Node in Code ViewApplies ordering to the list of types and functions in the Code View.

Editor Options

These are options specific to the editor. An example of the chosen styling appears at the bottom of the dialog.

OptionDescription
BackgroundThe background colour for the editor.
FontThe editor font.
Tab SizeThe width, in characters, used for displaying a Tab character.
Plain TextThe colour and style of plain text.
RemarksThe colour and style of comments, both Rem blocks and single-line ' comments.
StringsThe colour and style of quoted strings.
KeywordsThe colour and style of BlitzMax keywords.
NumbersThe colour and style of numbers.
MatchingsThe colour and style for bracket matchings.
CaretWhere supported, you can change the colour and width of the editor caret.

Tools Options

Provides some configuration options for the Output View and navbar.

Tool window customising

OptionDescription
OutputChange the foreground and background colours, as well as the font for the Output View.
NavbarChange the foreground and background colours, as well as the font for the navbar tree views.

App Stubs Management

Allows you to configure the available selection of app stub modules. Entries here appear in the App Stub Program menu.

App stubs management

Add a new entry by entering its name in the text field, and then clicking Add.

Entries can be removed by selecting them from the list, and clicking Remove.

Project Manager

The program manager provides a way to add your own Project folders to the Projects tree in the navbar.

Once a Project folder is added, the sources can be opened directly from the navbar by double-clicking on them.

The Project Manager

← Creating DLLsBlitzMax Make (bmk) →
  • Editing
    • Quick Menu
  • Building and Running
  • Errors
  • Debugging
    • Stepping Through Your Code
  • Toolbar
  • The Menus
    • File Menu
    • Edit Menu
    • Program Menu
    • Help Menu
  • Options
    • General Options
    • Editor Options
    • Tools Options
    • App Stubs Management
  • Project Manager
BlitzMax
Docs
Getting StartedDownloadsAbout
Community
ResourcesSyntaxBomb Forums
More
GitHubStarChat on Discord
Copyright © 2023 Bruce A Henderson