OWLMaker

OWLMaker

OWLMaker is primarily a GUI front-end to the OWLNext build scripts. It lets the user download, configure and build all the OWLNext libraries in a quick and simple way. It also provides a basic code editor with syntax highlighting.

Build features:

• Downloads the OWLNext source code for you.
• Supports the whole range of compilers for OWLNext.
• Allows easy selection of different build settings.
• Displays the output and summary of the build process.
• Can build multiple library configurations in parallel.

Additional features:

• Integrates Yura's CoolEdit so that source and make files can be browsed, inspected and edited for quick code changes.
• Integrates a function for converting resource files from the obsolete Borland format to the Microsoft format.

OWLMaker is itself an OWLNext application using many of the library features. For more information about the internals of the program, see the description in Examples.

Note to documentation authors and editors: OWLMaker has menu items, help buttons and links that refer to the URL of this page, as well as the exact anchors of the sections of the page (see Table of Contents below). If there is a change to the URL of this page or to any of the linked section headers (and hence the associated anchors), then the OWLMaker source code will have to be updated.

---

• OWLMaker
  • Requirements
  • Installation
  • Preparing the OWLNext source code
  • Using the OWLMaker Wizard
    • Page 1: OWLMaker Wizard main page
    • Page 2: Select toolset
    • Page 3: Select modules and build modes
    • Page 4: Select build options
    • Page 5: Confirm configurations and start the build process
  • Build process and results
  • Trouble-shooting
    • Issues with the "Stop build" command
  • Converting Borland resource files

---

Requirements

The latest version of OWLMaker can only build OWLNext 6.34 and later versions. If you need to build an earlier version of OWLNext, see OWLMaker Build 3175. This older version is now included in its own subdirectory in the main OWLMaker download archive, and OWLMaker will automatically offer you to run this older version, if it detects OWLNext source code older than version 6.34.

Note about 32-bit and 64-bit editions: The main executable in the OWLMaker download archive is now built for 64-bit Windows (x86-64 edition). However, a 32-bit edition is included in the "32-bit" subdirectory. If you run 32-bit Windows, make sure that you use the latter executable.

Note about Windows XP: The latest version of OWLMaker requires Windows Vista or later. It will not run on Windows XP and earlier versions of the operating system. Note that this only concerns OWLMaker and OWLNext 7. Earlier releases of OWLNext still support Windows XP. If you need to build an earlier release of OWLNext for development and/or deployment on Windows XP, you can use OWLMaker on Windows Vista or later to build OWLNext, and then transfer the resulting library files to Windows XP. If you only have access to Windows XP, and must build on this version of the operating system, then you have to use the command line. See our Installation Guide for more information on building OWLNext from the command line.

---

Installation

You can find the latest release of OWLMaker in our Files download area. To install it, simply download the compressed package, unpack it into a writable location, and run the extracted program.

Note: For OWLMaker Build 4610 and later, you can update to the latest version by selecting "Help | Check for updates" from the main menu. OWLMaker will then check whether there is a newer version available for download in our Files area here on the OWLNext project site. If so, you are given the option to perform an update. OWLMaker will do the rest by downloading the program archive "OWLMaker.zip", unpacking it to a temporary folder, extracting the correct executable and overwriting the old. OWLMaker is automatically closed and restarted, making the whole update as simple and seamless as can be.

---

Preparing the OWLNext source code

Before you can use OWLMaker, you of course need the OWLNext source code to build. With OWLMaker Build 4764 and later, installing the source code is now easier than ever. A new command "Tools | Download source code" is now available, and the same command is conveniently available via the button "Download source code" on the start page of the OWLMaker Wizard. The download command allows you to select among the latest available releases in our Files download area, and OWLMaker will automatically download and unpack the selected archive. You can also select to download documentation at the same time.

If you need to install and build a version of OWLNext that is not available with the download command, then see our Installation Guide for more information and step-by-step instructions on how to obtain a snapshot of any version of the source code available in our Code repository.

---

Using the OWLMaker Wizard

To start configuring the build, select "Tools | OWLMaker Wizard", or simply click on the corresponding button on the toolbar.

Note: The following sections describe the latest version of OWLMaker made for OWLNext 6.34 and later. If you use OWLMaker Build 3175 or earlier for OWLNext 6.20 to 6.32, see OWLMaker Build 3175.

Page 1: OWLMaker Wizard main page

Enter or locate the root folder of OWLNext and click Next. The selected folder will be examined to confirm that it contains a supported version of OWLNext. An error will be shown if it does not.

You can download the OWLNext source code by pressing the button "Download source code". OWLMaker will then load the index for the versions available from our Files download area, and if all goes well, you will be presented with a selection dialog titled "OWLNext source code download", where you can choose the version you want. You can here choose to include documentation as well. Specify the desired destination folder, and press "Download". The download will proceed, and if successful, you will return to the OWLMaker Wizard start page with the destination folder path filled into the "OWLNext root location" field.

Alternatively, see Installing OWLNext for instructions on how to download any version of OWLNext from our project site.

If the OWLROOT system environment variable is set, you will also have a button "Locate" on the wizard start page. Pressing the button will put the value of OWLROOT into the field "OWLNext root location".

Page 2: Select toolset

Select in the list the product you want to use to build OWLNext.

Note that OWLMaker intelligently displays only the supported development tools for the detected OWLNext version in the root location specified on the previous page. The detected version is given at the top of the page. Go back and change your root if the detected version is not the version you intend to build.

For further information about the supported toolsets for each version of OWLNext, see Supported Compilers.

After you have selected a toolset, enter the location of the product, or use the Locate button if available. Note that some toolsets, such as Borland C++ 5.5, are not able to automatically locate the product. In this case, the Locate button will be disabled, and you will have to enter the location manually, or you can use the browse button to the right of the field.

Note that the automatic location detection for Visual Studio 2017 and later is very rudimentary. It only looks in the standard installation location. So if you have installed Visual Studio in a custom location, and you get an error when you press the Locate button, then you will have to enter the root location manually. Also, note that for the Microsoft toolsets, the root location is the path to the "VC" folder within the product folder. For example:

C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC

Page 3: Select modules and build modes

Select the combination of libraries and build modes that you want to build.

The page shows brief information on each option as you highlight it. For further information, see the OWLNext Knowledge Base, in particular OWLNext modules, OWL compatibility build modes, Multi-threading and OWLNext, Unicode and OWLNext, as well as the FAQ | Should I use static or dynamic linking (DLL)?

OWLMaker will only display the options that are applicable to the version of OWLNext you are building and the tools you use to build. Click on the items to display information about each module and build mode. Use the context menu (right-click) in the list to choose default settings or quickly set or clear all checkmarks.

However, note that for version 7 and earlier the CoolPrj module does not support Unicode, so Unicode build configurations will not be generated for this module, even if the CoolPrj module and the Unicode character set mode are both selected.

Also note that you must select at least one option in each build mode group for the Next button to become available.

Trouble-shooting: If the Next button stays disabled whatever you do, try to select "Select default" from the context menu (right-click) in the list.

Page 4: Select build options

Use cross-compilation for targeting [x86/x64/all]

Cross-compilation for 64-bit targets must be selected if you are not running OWLMaker on a 64-bit operating system or you do not have a native 64-bit toolset installed. Cross-compilation for 32-bit targets is useful if you are running OWLMaker on a 64-bit operating system and want to benefit from the larger memory space available to 64-bit toolsets. In some cases, this may allow you to perform more builds in parallel without running into errors due to memory limitations.

Enable multiprocessing in the toolset

This option enables concurrent compilation within each library configuration, if supported by the toolset and the OWLNext version. This can greatly speed up the build on multi-core and multi-processor systems. For the Microsoft toolsets, this setting controls the /MP compiler option. For the Clang-based toolsets in Embarcadero RAD Studio and C++Builder, it controls the --jobs compiler option. Embarcadero's classic Borland-based toolsets and Microsoft's toolsets before Visual Studio 2008 do not support this option.

Build configurations in parallel

When this option is selected, OWLMaker will build the selected library configurations in parallel, if possible, further increasing the speed of the build. Note that, due to dependencies, build setup will always be sequenced before the rest of the build, and the core library configurations will be sequenced before extension library configurations. Also note that the parallel build option is only available if you have selected more than one configuration and the selected toolset and OWLNext version support parallel builds.

Note: Since [r6836], you can now select the number of parallel configurations OWLMaker will build in parallel. OWLMaker limits the batch size to half the number of logical processors available. This limit reduces the likelihood of overloading the system, although overloading can still occur, resulting in build failure. If this option overloads your system, try turning off "Enable multiprocessing in the toolset". Doing so should make the build commands for the individual library configurations less demanding.

Also note that modern mainstream CPUs usually come with 2-way SMT (simultaneous multi-threading), which means they have 2 logical processors per physical CPU core. So, in effect, the maximum batch size is limited to the number of physical cores on most systems. For example, an 8-core AMD Ryzen 7 1700 has 16 logical processors with SMT enabled (which is the default setting). On a system with this CPU, OWLMaker will at most issue 8 build configurations in parallel.

Continue on failed builds

When you use this option, the batch will not stop even if a particular module or configuration produces build errors. This is mostly useful for running build tests after making changes to the OWLNext source code. The release versions of OWLNext should normally build without errors.

Show message box when done

If you want to be notified with a sound and a pop-up message box when the build is done, then select this option. If not, leave this option off, and OWLMaker will then just quietly show the build results when it has completed.

Build order

Since [r6836], you can now specify the preferred build order. Previously, OWLMaker would build all configurations in a module before moving on to dependent modules. Now, you can choose to order by configuration instead. In this case, the build proceeds on a configuration-by-configuration basis. For example, once the debug ANSI configuration of the OWL module is built, the debug ANSI configuration of OCF can proceed immediately, without waiting for all the other configurations in the OWL module to complete.

Build order | Terms

Separate terms by space. Any build order terms specified will be used to prioritize matching configurations. A term matches a configuration if it is found within the target file name (see OWLNext Library Files Naming Convention). For example, if you specify "cool x64 -d", OWLMaker will prioritise 64-bit debug configurations of the CoolPrj module. The order of the terms is significant. Earlier terms are prioritized before later ones, with each term in effect performing a nested partitioning. However, note that module dependencies will override the specified terms. For example, CoolPrj depends on OWL and OWLExt, so these dependencies will have to be built before CoolPrj.

Perform build setup

This option performs automatic build setup. Build setup is required the first time you build OWLNext, to create the header file "include/owl/version.h". If selected, OWLMaker will pass "SETUP=1" to the build scripts causing automatic build setup to be performed. For more information about build setup, see "Perform build setup" in the OWLNext installation guide.

Delete old output files before build

This option is similar to a make file "clean" command. When selected it will force a full rebuild of the library. Hence it has the same effect as a "Rebuild" command in Visual Studio (which is equivalent to a "Build" command in RAD Studio). If this option is not selected, only missing or outdated files will be rebuilt. This is equivalent to a "Build" command in Visual Studio (which is equivalent to a "Make" command in RAD Studio). Note that OWLMaker can give more accurate progress indication throughout the build when this option is selected, since the total number of files to build is then known.

Delete intermediate files after successful build

This option will clean the "*.obj" and other intermediate files after a successful build in order to free disk space. If the build fails, all the intermediate files from all the configurations are left intact. This allows you to fix the problem and restart the build, while deselecting "Delete old output files before build", to rebuild only the failed and outstanding files.

Page 5: Confirm configurations and start the build process

The last page shows the commands that will be executed and the resulting libraries that will be built. Select Back to make any changes. If all is well, then click Finish to start the build process.

---

Build process and results

While the build executes, OWLMaker will show progress indication on the program status bar, as well as on the program icon on the Windows Taskbar. To abort the build, select the "Stop build" command from the Tools menu, or click the corresponding button on the toolbar. After the build has finished, the build output, warnings, errors and resulting target files, with build status and timing, will be shown in the Build Output window inside OWLMaker.

Use the toolbar to navigate between errors and warnings. You can press Enter or double-click a message to open the associated file in the integrated editor.

---

Trouble-shooting

If you have an issue with OWLMaker itself, or you get a build error, then check out our FAQ and OWLMaker bug tickets. If those do not help, try posting about the issue in our Discussion forum.

Issues with the "Stop build" command

In older OWLMaker versions before [r6831], and for some toolsets, it may take a long time for the command to have an effect. More importantly, in some cases the program environment (the internal program execution state) may become corrupted after the aborted build command, and subsequent build commands may fail in various ways. For example, OWLMaker may fail to perform build setup correctly [bugs:#534].

To circumvent such issues, restart OWLMaker and try again.

---

Converting Borland resource files

The Microsoft resource script format (RC) does not support in-lined bitmaps (see Converting Borland C++ Resource Files to Visual C++). In the Borland resource script format, a bitmap resource can be embedded within the resource script, encoded as a hexadecimal stream, whereas in the Microsoft format the script must reference an external bitmap file.

To help you convert your Borland RC files to the Microsoft format, OWLMaker integrates a function for extracting in-lined resource bitmaps from Borland RC files. This function will create an external file for each in-lined bitmap, icon and cursor found in the specified file.

Usage:

• Select Tools | Extract resource bitmaps.
• Select the Borland-style resource file you want to convert.
• Specify the output folder for the bitmaps.
• Press Extract.

If the conversion succeeds without errors, a list of the created bitmap files will be shown in the message window, and the converted resource file will be loaded in the editor.