Coding guidelines for 64-bit apps

You can create 64-bit desktop, web and console apps for Mac, Windows and Linux. In most cases, you'll be able to build a 64-bit version of your existing projects without having to make any changes. As of 2017 Release 3, the Xojo IDE itself is also 64-bit. With 64-bit, your apps gain access to much more memory than before (32-bit apps had a 3-4GB limit) and math-based code can see significant speed increases due to the new optimizing compiler. In addition, 64-bit operating systems can run 64-bit apps more efficiently than 32-bit apps since they do not have to load an extra compatibility layer.

Creating a 64-bit app

../../_images/coding_guidelines_for_64-bit_apps_build_architecture.png

The Inspector for each build target (Windows, macOS and Linux) has a property called Architecture where you can select the type of architecture you want to build. To create a 64-bit app for your existing projects, change the Architecture setting to a 64-bit target and then press the Build button.

Coding notes

Compiler constants

In a 32-bit app, Target32Bit returns True and Target64Bit returns False.

In a 64-bit app, Target64Bit returns True and Target32Bit returns False.

Use these two compiler constants to determine the architecture of the app.

Integers

in a 64-bit app, the Integer data type is an alias for Int64 and UInteger is an alias for UInt64. In a 32-bit app, the Integer data type is an alias for Int32 and UInteger is an alias for UInt32.

Declares

In general, you'll want to review any Declares that are used in your project. In particular, if a Declare is using a specific Integer type, such as Int32, it may be possible that the library requires you to use Int64 in a 64-bit app. To simplify this, use the Integer data type which is an alias to Int32 in 32-bit apps and Int64 in 64-bit apps.

On Mac, some macOS declares require a floating-point number. The 32-bit libraries use Single, but the 64-bit libraries use Double. For these situations you should use the CGFloat data type.

A 64-bit app can only use 64-bit libraries. Declaring to a 32-bit library from a 64-bit app will fail. Similarly, a 32-bit app cannot use 64-bit libraries.

Building notes

The type of app you need to build for your users varies based on the operating systems you need to support.

macOS

All versions of macOS supported by Xojo are already 64-bit.

Windows

Windows is available in both 32-bit and 64-bit versions. The 32-bit version of Windows cannot run 64-bit apps, but the 64-bit version of Windows can run both 32-bit and 64-bit apps. This means you will likely need to create both 32-bit and 64-bit versions of your Windows apps so that your users can choose the appropriate one for their version of Windows. Keep in mind that the TargetWin32 compiler constant returns True on Windows, regardless of whether the app is 32-bit or 64-bit. This constant is indicating that the Win32 API is being used and is not an indicator of 32-bit or 64-bit systems. To check if the app is 64-bit, use the Target64bit compiler constant.

Build files

For 64-bit builds, the compiler places some framework DLLs next to the executable and not into the "MyApplication Libs" (or just "Libs") folder like it did for 32-bit builds.

A little history: For 32-bit Windows builds, the compiler doesn't actually spit out a native PE32 file. What it does is writes out a stub executable and then tacks all of the program data onto the end of it. The stub is responsible for loading that data into memory and performing all of the relocations and import binding that the OS loader would normally do. The stub doesn't have to link directly against any of the libraries referenced by the program (including the framework), so Xojo has the freedom to put the DLLs required by the program anywhere. However, this approach occasionally gets apps flagged as malware by antivirus programs and prevents some features Windows users have wanted for ages (like the ability to edit the app manifest).

For 64-bit Windows executables, the compiler is using a native linker to generate actual PE32+ files. These executables link directly against whatever DLLs it needs and are therefore bound to the operating system's search path. In order for the loader to find the DLLs the executable need to launch, they have to be in the same folder as the executable itself. Currently, Visual Studio runtime DLLs appear next to the executable along with the Xojo framework DLL (XojoGUIFramework64.dll). If you use WebKit with HTMLViewer then CEF3 related files and DLLs also appear alongside the executable.

Attempting to the make the Windows build structure look more like macOS bundles is unlikely to happen, primarily due to the DLL issue but also because in Windows, the directory is the application bundle. Microsoft expects programs to use installers and doesn't really care how 'messy' your program's folder is. That said, the change in directory structure does not impose a requirement that installers are used or that it has to be on the system disk. The only change is that there will be more files in the folder with the executable.

../../_images/coding_guidelines_for_64-bit_apps_windows_64-bit_advanced_build_settings.png

Manifest file

For Windows 64-bit apps a standard manifest is used. The manifest includes information from the Windows Build Settings, including version information, OS settings and RunAs settings.

Linux

Linux distributions are also available in both 32-bit and 64-bit versions, although 64-bit versions are far more common. In fact, some Linux distributions are no longer making 32-bit versions available.

32-bit versions of Linux cannot run 64-bit apps. 64-bit versions of Linux can run 32-bit versions of app, but only if the appropriate 32-bit compatibility libraries have been installed. These libraries are not typically installed by default and are not always easy to install. This means you will likely want to create both 32-bit and 64-bit versions of your Linux apps so that your users can choose the appropriate one for their version of Linux.

Plugins

A 64-bit app requires plugins that support 64-bit. If your app uses plugins, you should check with your plugin vendor to see if they have updated versions that support 64-bit.

Also note that since the Xojo IDE itself is 64-bit, any plugins you use must have a 64-bit plugin part in order for the IDE to recognize them. This is true even if you are building 32-bit apps.

IDE script for building

To make it easier to build all the different versions of your app in one step, you can use the following IDE Script:

' Build all target platforms
Const kOSX32 = 7
Const kOSX64 = 16
Const kWin32 = 3
Const kWin64 = 19
Const kLin32 = 4
Const kLin64 = 17
Const kLinARM = 18

Var path As String
path = BuildApp(kOSX32)
path = BuildApp(kOSX64)
path = BuildApp(kWin32)
path = BuildApp(kWin64)
path = BuildApp(kLin32)
path = BuildApp(kLin64)
path = BuildApp(kLinARM)

Var result As String
result = ShowDialog("Build All", _
  "Finished building.", _
  "OK", "", "", -1)

This script creates Windows, macOS and Linux builds for both 32-bit and 64-bit plus a Raspberry Pi build (ARM 32-bit) all in one step. You can comment out the parts you do not need to build.

Other 64-bit information

For some projects, 64-bit builds can take longer to finish. Be sure to let Xojo finish building. For best speed set Optimization Level to "Default" in the Shared Build Settings.
To reduce build times, ensure you do not have really long methods that can be refactored and simplified. Project items (classes, Windows, etc.) with large amounts of code can also increase build times. Break them into separate classes to reduce build times.
Arrays can have a maximum index value of 2,147,483,646.

Troubleshooting

If you are unable to build your project as 64-bit, please create an issue and attach the project, along with additional information such as the platform you are using and anything relevant from the system log.