Console apps

Unlike iOS, desktop and web apps, console apps are not event-based. Console apps have no graphical user interface and are designed to run from the terminal, command line or as a background process.

Console project overview

When you create a console project, you get the following project items added automatically:

• App: The App object is where your put the code to run.

App Object

For a console project, the App object is a subclass of ConsoleApplication, but you can also choose to change the Super to ServiceApplication to create a Windows Service.

Event Handlers

The Application class for a console app has these event handlers:

• Run: This event handler is called when your app first starts, either by running the app from Xojo or by running a built app. Your app quits when the Run event ends or you call the Quit method. You can manually quit the app by pressing Control-C in the console/terminal.

• ConsoleApplication.UnhandledException: Executes when a runtime error occurs that is not caught by your code. This event gives you a “last chance” to catch runtime errors before they cause your app to terminate.

Background apps

Console apps are often used to create background apps. On macOS and Linux, background apps are called daemons. On Windows, background apps are called services.

Daemon

To turn your console app into a daemon that can run in the background, call the Daemonize method of the ConsoleApplication class from the Run event handler.

If Not Daemonize Then
  Quit
End If

You can also use the Daemonize method on macOS, but Apple would rather you use launchd to start daemon processes.

Service Application

To create a console app that can run as a Windows Service you need to use the ServiceApplication class. After you create your console app, change the Super of the App from ConsoleApplication to ServiceApplication. Alternatively you can choose ServiceApplication from the Templates in the Project Chooser.

A service app gives you additional events that help you manage things when the services starts, stops or is paused. Refer to ServiceApplication for more information about these events.

Build Settings

The Build Settings section of the Navigator contains the build-specific settings for your app in general and for specific OS targets. You can check the box next to each target in order to build an app for that target. Console targets are: Windows, macOS and Linux.

Shared

The Inspector for Shared settings contains these properties:

• Major Version: The Major version for your app. Version numbers are usually written as 1.2.3.4, where “1” is the major version.

• Minor Version: The Minor version for your app. Version numbers are usually written as 1.2.3.4, where “2” is the minor version.

• Bug Version: The Bug version for your app. Version numbers are usually written as 1.2.3.4, where “3” is the bug version.

• Stage Code: Used to indicate the type of app you are building (Development, Alpha, Beta, Final).

• Non Release Version: The Non Release (build) version for your app. Version numbers are usually written as 1.2.3.4, where “4” is the non release version.

• Auto Increment Version Info: When ON, the Non Release Version increases by one each time you do a Build.

• Short Version: A short text description for your app. Usually this contains just the version number (such as 1.2.3.4) and is displayed by some operating systems in Get Info or Property windows for the application.

• Long Version: A longer text description for your app. Usually this contains the application name, copyright, version and other information. This is displayed by some operating systems in Get Info or Property windows for the application.

• Package Info: A text description for your app that may be displayed by some operating systems in Get Info or Property windows for the application.

• Use Builds Folder: When ON, a separate folder is created alongside the project file. Each platform (macOS, Windows, Linux) also gets its own subfolder within this builds folder.

• Include Function Names: When ON, the actual names of your function calls are included in the built app. This is useful for debugging purposes and for getting stack traces.

• Language: The language to used to resolve dynamic constants.

• Optimization: Used for all 64-bit builds and 32-bit ARM builds (those that use the LLVM compiler). There are these choices:

• Default: Optimized for fast build times.

• Moderate: A balance between build times and math-related code execution time.

• Aggressive: Longer build times, but code is more optimized for faster math-related code execution time.

• Command Line Arguments: These are the command-line arguments that are passed to your app when running it from Xojo.

• Destination: Specifies the path where the running app is placed. Normally it is placed alongside your project, but you can choose a different location.

macOS

The macOS section contains settings used when building the macOS app.

• Mac App Name: The actual file name for your macOS app.

• File Types: n/a

• Architecture: The CPU architecture for the app. Choices are x86 64-bit, ARM 64-bit and Universal.

• Bundle Identifier: The bundle identifier is required by macOS and is used as a unique descriptor for your app. It is usually specified as a reverse domain name, such as com.xojo.myapplication.

Windows

The Windows section contains build settings for your Windows apps.

• Windows App Name: The actual file name for the Windows app.

• Company Name: The “Company Name” appears in the Copyright section of the app properties in the Details tab.

• Product Name: The name of the product as installed in the Windows Start > All Programs menu. This also appears in “Product name” on the app properties Details tab.

• Internal Name: This is useful when your product has a different internal name than its external name. This is not shown on the app properties Details tab.

• File Description: [TBD]

• Include Windows Runtime DLLs: Copies the Universal Runtime DLLs beside your app executable. For more information, refer to Windows Universal Runtime.

• Architecture: The CPU architecture for the app. Choices are x86 32-bit, x86 64-bit and ARM 64-bit.

Linux

The Linux section contains build settings for your Linux apps.

• Linux App Name: The actual file name for the Linux app.

• Architecture: The CPU architecture for the app. Choices are ARM 32-bit, x86 32-bit, x86 64-bit and ARM 64-bit. Linux ARM apps run on the Raspberry Pi and other similar single-board computers.

This Computer

The This Computer section shows you the appropriate target settings (macOS, Windows or Linux) for the OS you are currently using. For example, if you are running Xojo on macOS, then This Computer shows the macOS Build Settings.

Deployment

To create a stand-alone app for deployment, you create a build by clicking the Build button on the main toolbar or choosing Project > Build from the menu. This creates apps for each of the OS platforms you selected, with separate folders for each (when Use Build Folders is ON).

Console apps are deployed by installing them on a computer and running them on the computer.

Console apps have two parts: the main executable and its libraries (contained in the Libs folder). Both parts are required in order for the app to run.

You can just zip the console app and its Lib folder for distribution.

OS	Architecture	Build Folder Name
Linux	x86 32-bit	Linux
Linux	x86 64-bit	Linux 64 bit
Linux	ARM 32-bit	Linux ARM
Linux	ARM 64-bit	Linux ARM64
macOS	x86 64-bit	macOS 64 bit
macOS	ARM 64-bit	macOS ARM 64 bit
macOS	Universal	macOS Universal
Windows	x86 32-bit	Windows
Windows	x86 64-bit	Windows 64 bit
Windows	ARM 64-bit	Windows ARM 64 bit

macOS

On macOS, you can start a console app from the Terminal. Navigate to the folder containing the app and type its name at the Terminal prompt. You will need to include the prefix "./" in order for the Terminal to actually find the app in the current folder:

./MyApp

Windows

On Windows, you can start a console app from the Command tool. Just type its name at the command prompt:

MyApp

Linux

On Linux, you can start a console app from the Terminal. Navigate to the folder containing the app and type its name at the Terminal prompt. You will need to include the prefix "./" in order for the Terminal to actually find the app in the current folder:

./MyApp