Creating Standalone Exes

1-May-2016
Tom Mulgrew

Basic4GL standalone executablesCreating the executableIf your file doesn't runCreate standalone exe options"Program" tab"Options" tab"Screen Mode" tab"Embedded Files" tabAbout the executable fileNot machine codeFile sizeLicensing

Basic4GL standalone executables

Basic4GL can take any Basic4GL program and create a Windows executable file. This program can run on its own, and does not require Basic4GL to be installed.

Creating the executable

To create a stand-alone executable:

The create standalone exe options dialog box will appear. You can now configure how your exe will be created.

It is recommended you at least set the filename, so you can choose a directory where you will be able to find the file once it's created (otherwise by default the file will be created in the same directory as the original Basic4GL source file.).

When you are ready, click "OK" to generate your exe file.

Generate file errors

Standalone exe file generation can fail. One common and simple reason is that you don't have access to create the file in the folder specified, due to Windows folder security.

If this happens, try one of the following:

Basic4GL will create the executable file, and display it in a Windows Explorer window. You can then double click it to run the file.

If your file doesn't run

There are some common reasons a standalone executable might not run, or not run correctly.

Missing asset files

Be aware that your program may not run correctly if it requires files (such as images, sound files) that it cannot access from the folder containing the standalone executable.

For example, if your program loads a texture from a relative folder, e.g.

dim myTex = LoadTex("data\ball.png")

Then it will fail if the standalone executable's folder doesn't contain a subfolder "data" containing an image file "ball.png".

You will need to distribute these files along with your standalone executable, or as an "embedded file" inside the executable itself (see the "Embedded Files" section below).

Missing plugins

If your program uses plugin libraries, then their DLLs, and any other resources that they use will need to be copied into the standalone executable's folder as well. Otherwise the standalone executable file will not start.

Copying plugin files

Basic4GL does not try to automatically copy plugin library DLLs into the target folder for you. This is because it does not know which files are actually required.

A plugin library DLL often references other DLLs, and may have its own asset files that it loads at runtime. Instead of trying to guess (and likely getting it wrong much of the time) Basic4GL leaves it up to you to determine which files need to be distributed.

Refer to the plugin library documentation to determine which files are required.

B4GLSound.dll

If your program plays sound effects or music, you must copy B4GLSound.dll into the standalone executable file's folder. Otherwise no sound or music playback will occur (your program will be silent).

Create standalone exe options

There are several ways you can configure how the program will work, and how and where it will be created. These are divided into several tabbed pages in the "Create standalone exe" dialog box.

"Program" tab

This allows you to specify the output filename, and the window title (which is also shown when you Alt-Tab between applications).

By default the name of the Basic4GL program is used (i.e. "MyGame.gb" will create a file "MyGame.exe", with a window title "MyGame"). If the Basic4GL program hasn't been saved to disk yet, it will default to "MyProgram.exe" (filename) and "MyProgram" (display name).

"Options" tab

This allows you to specify what will happen when the program encounters a runtime error, or reaches the end of the program (or an "end" command). There are two options:

When the program finishes

Some programs keep on executing until the user quits (presses Escape or closes the window). Others will perform an action, display the results and then finish.

Here you can specify whether it is appropriate to close the program down immediately, or wait for a keypress (to give the user time to look at the results on the screen) before closing. You can also choose to keep the window open until the user closes it by clicking on the close button. (This option does not apply when in full screen mode.)

If a runtime error occurs

Typical runtime errors include:

If an error like this occurs the Basic4GL program cannot continue and must stop. In Basic4GL it would position the cursor where the problem is and give a description of what went wrong.

Here you can specify what your standalone executable program should do.

"Esc" or Closing Window quits

Choose whether the program should stop if the user presses the "Esc" key on their keyboard, or clicks the "X" to close the window (if in Windowed mode).

If you have implemented your own quit function (using the BASIC "end" command), you may want to untick this option to prevent the program from inadvertently closing. Your program may have clean-up logic to run before the user quits, such as saving preferences to a file, or just asking "are you sure?".

Include a quit function

If you untick this option, make sure you build a quit function into your program.

Otherwise the user will not be able to close your program (besides killing it from the Windows Task Manager).

Example 1:

printr "Press Q to quit"
while lcase$ (inkey$ ()) <> "q"

    ' Do something
    ' ...
                  
wend

' Cleanup 
' ...

printr "Goodbye"

Example 2:

printr "Press Q to quit"
while true
    
    ' Do something
    ' ...
    
    if lcase$ (inkey$ ()) = "q" then

        ' Cleanup 
        ' ...

        printr "Goodbye"        
        end
    endif
wend

Basic4GL will simulate a VK_ESCAPE keypress if the user clicks the close button on the window (in windowed mode).
You can detect this as follows:

if InScanKey () = VK_ESCAPE then
    
    ' User wants to quit
    ' ...

endif

"Screen Mode" tab

Choose the screen mode your program will run in. This is similar to the Basic4GL runtime options dialog box.

Some options are only applicable in certain configurations. For example the "Colour depth" can only be specified if you are in full screen mode (in windowed mode, the desktop colour depth will always be used). These options will be grayed out when not applicable.

"Resolution", "Colour depth" and "Full screen"

These are the main options for defining the window behaviour.

"Border around window" and "Allow resizing"

These allow extra control of how the window will behave in windowed mode.

The window border shows the title and the maximize, minimize and close buttons.

"Allow resizing" means that the user can drag the sides/corners of the window to change its size.

"Enable stencil buffer"

This is an advanced option, and only required if you are writing OpenGL code that uses the OpenGL stencil buffer. (Otherwise leave it un-ticked.)

Startup

You can also choose not to create an OpenGL window at all when your program starts up. In this case no window is displayed until your program creates one with the UpdateWindow() command.

This can be useful if your program lets the user choose the window resolution (and maybe writes the settings to a file that it loads when it starts up).

Alternatively your program doesn't use the OpenGL window at all, such as run-and-quit programs that operate on files etc.

Important!

Be careful not to execute any OpenGL, text or sprite commands before the OpenGL window has been created. Otherwise your program will error with "An exception has occurred", and stop.

"Embedded Files" tab

Many programs require extra files in order to run properly, such as textures and data files. If the program cannot find them, it won't run correctly and may not run at all.

Normally this means you have to distribute all these files separately, either in a compressed archive (like a zip file) or using some sort of installer.

Basic4GL has an "Embedded Files" mechanism which can simplify this by storing the support files directly into the executable file itself. These files load automatically whenever the program loads in a file with the same filename - for example using LoadTex, LoadSound or OpenFileRead - so you don't need to change your program to make it work.

If the file isn't found inside the executable, the program will attempt to load it from disk as per normal.

Default embedded files

Basic4GL will attempt to guess which files your program uses by scanning for text strings that match up to filenames on your disk, and add them to the embedded files list automatically.

However this is a fairly primitive algorithm, and does not always detect all files used. For example:

dim path$, filename$, tex
path$ = "textures"
filename$ = "00001.jpg"
tex = LoadTexture(path$ + "\" + filename$)

Will load a texture called "textures\00001.jpg", but Basic4GL will not detect this as it sees "textures" and "00001.jpg" separately. If you want this file to be embedded, you must add it manually.

Alternatively you may prefer to distribute files normally, and not to embed them at all. In this case you should remove them from the list, so that they don't make the executable file unnecessarily large.

Adding embedded files

Click the "Add..." button, browse to the files you want to include, select them and click "Open". Do this as many times as necessary.
Note: Simply adding a file doesn't mean that the program will use it. You still have to write the Basic4GL code to load and use the file. Otherwise it will sit in the executable and waste space.

Deleting embedded files

Sometimes you don't want to use the embedded files mechanism.

For example, you may want to distribute an image separately so that the user can edit it and customise their game.

Also embedded files are loaded into memory as soon as the program starts (even if they aren't used), and will use this memory until the program exits. If you have a large number of data files you may want to load them in as they are required and then free them up once you are finished with them. In this case distributing the files separately might be a better idea.

To remove files from the embedded files list, select them and click "Remove".

About the executable file

A few other things to be aware of:

Not machine code

Basic4GL standalone executable files are not compiled to machine code.

They contain the same virtual machine as the Basic4GL editor, and run the same op-codes exactly the same way as the Basic4GL editor.

This means that standalone executable files do not run any faster than the same program running in Basic4GL itself.

File size

Even simple Basic4GL programs create standalone executables of at least 1.2 megabytes.

This is because all standalone executables contain:

These are contained in every standalone executable regardless if they are used or not.

Licensing

Refer to the "STANDALONE EXECUTABLES" section of License.txt distributed with Basic4GL for licensing and distribution of standalone executables created with Basic4GL.