Install on macOS
Guided Installation
Two approaches for installing and using ADOxx are available for macOS:
- Normal mode: uses an ADOxx application package that can be moved into the Applications folder.
- Expert mode: uses Z shell (zsh) scripts in a terminal to step through the process and installs ADOxx in your HOME folder.
The installation has been tested on macOS 14.0 Sonoma.
Normal Mode
To install ADOxx on macOS (normal mode):
- (once) Get an ADOxx license key if you don't have one yet. It is available from the ADOxx homepage.
- Download the
.zip
package with the files for macOS from the ADOxx homepage. - Extract the downloaded
.zip
file to a location of your choice. - Open the
.dmg
file from the extracted location to mount the file and open the package. - Drag and drop the ADOxx application into the "Applications" folder.
- Unmount the
.dmg
file. - Start the ADOxx application from the "Applications" folder.
In case of "cannot verify developer"
In case a warning like "macOS cannot verify the developer of “ADOxx 1.8.0”. Are you sure you want to open it?" is shown, right-click the ADOxx app, select open and confirm that you want to open.
- Select "ADOxx 1.8.0 Development Toolkit" in the pop-up. When started the first time a pop-up will inform of additional dependencies.
- Confirm the message and step through the process in the terminal window.
- Dependencies are installed as necessary during this step.
- Your administration password is required during these installation steps.
In case you face any issues during installation, please have a look at the corresponding Troubleshooting section.
Expert Mode
To install ADOxx or an ADOxx based tool on macOS (expert mode):
- (once) Get an ADOxx license key if you don't have one yet. It is available from the ADOxx homepage.
- Download the
.zip
package with the expert installation files for macOS from the ADOxx homepage. - Extract the downloaded
.zip
file to a location of your choice. - Open a terminal window and navigate to the extracted location.
- Execute the script
./install_on_macos.sh
.- If the script can not be executed, then give it execution permissions with the command
chmod +x ./install_on_macos.sh
and try again.
- If the script can not be executed, then give it execution permissions with the command
- Follow the instructions of the installation script.
- Dependencies are installed as necessary during this step.
- Your administration password is required for the installation.
In case you face any issues during installation, please have a look at the corresponding Troubleshooting section.
Guided Uninstallation
Normal Mode
To uninstall ADOxx on macOS (normal mode):
- Move the ADOxx application from the "Applications" folder to the recycle bin.
- (optional) Uninstall Wine and Homebrew in that order if they are no longer needed.
Expert mode
To uninstall ADOxx or an ADOxx based tool on macOS (expert mode):
- Open a terminal window and navigate to the of the installer files (extracted location for installation).
- Execute the script
./uninstall_on_macos.sh
.- If the script can not be executed, then give it execution permissions with the command
chmod +x ./uninstall_on_macos.sh
and try again.
- If the script can not be executed, then give it execution permissions with the command
- Follow the instructions of the uninstallation script.
Wine and Homebrew
ADOxx and ADOxx based tools require Wine to run on macOS. Wine is installed using Homebrew. These are installed as part of the installation process. Only remove them if you no longer need them for any other applications, for example other ADOxx based tools etc.
Dependencies
ADOxx and ADOxx based tools require the following to run on macOS:
Additionally the tool requires a database to store the data:
- Currently the default database system used is SQLite.
- Alternatively Microsoft Azure SQL Edge can be used via an ODBC connection. See Using Microsoft Azure SQL Edge as DBMS for details.
Manual Installation
The following describes the steps necessary to manually install and set up the ADOxx platform on macOS. It can be roughly described by the following steps:
- Install necessary dependencies.
- Install the database management system.
- Create a Wine-prefix.
- Copy the ADOxx application files.
- Set up the ADOxx database.
- Create shortcuts for the Development Toolkit and the Modelling Toolkit.
Adapt the commands in the following sections as necessary for your system and the used ADOxx tool version.
Install Dependencies
- Install Homebrew
- Installation details are provided on their homepage.
- Take note of any information and warnings the Homebrew installer provides at the end. Often additional commands and restarting the terminal are necessary to finish the Homebrew installation.
- Install Wine through Homebrew.
- First run the command
brew tap homebrew/cask-versions
to get access to the correct Wine version. - Then run the command
brew install --cask --no-quarantine wine-staging
to install Wine.
- First run the command
Install Database Management System
The current version of ADOxx uses SQLite for managing a simple database file by default. No special installation is needed for this case, as the necessary files are provided with ADOxx.
If necessary, it is also possible to use a Microsoft Azure SQL Edge to manage the database. Some details are described in the Using Microsoft Azure SQL Edge as DBMS section.
Create Wine-prefix
- Create a Wine-prefix where ADOxx will run out of.
- Run a command like:
LANG=en_US WINEARCH=win64 WINEPREFIX=${HOME}/.wine_adoxx18 WINEDEBUG=-all wine64 cmd /c exit
- Run a command like:
Copy ADOxx Application Files
- Extract the contents of the
.zip
file containing the built ADOxx files, for exampleinstall-support/ADOxx_1.8.0.zip
, to a folder in the Wine-prefix, for example"${HOME}/.wine_adoxx18/drive_c/Program Files/BOC/ADOxx_1.8.0/"
(in Wine:"C:\Program Files\BOC\ADOxx_1.8.0\"
). - Set the application files to trustworthy by running the command
sudo xattr -r -d com.apple.quarantine "${HOME}/.wine_adoxx18/drive_c/Program Files/BOC/ADOxx_1.8.0/"
.
Set Up Database
- Run the
asetlic.exe
tool from the ADOxx installation directory with the arguments"-plicense.ini" "-Lalicdat.ini"
and specify the customer number and license number.- Run a command like:
LANG=en_US WINEARCH=win64 WINEPREFIX=${HOME}/.wine_adoxx18 WINEDEBUG=-all wine64 "C:/Program Files/BOC/ADOxx_1.8.0/asetlic.exe" "-p${HOME}/.wine_adoxx18/drive_c/Program Files/BOC/ADOxx_1.8.0/license.ini" "-L${HOME}/.wine_adoxx18/drive_c/Program Files/BOC/ADOxx_1.8.0/alicdat.ini"
- Run a command like:
- Run the
adbinst.exe
tool from the ADOxx installation directory.- Run a command like:
LANG=en_US WINEARCH=win64 WINEPREFIX=${HOME}/.wine_adoxx18 WINEDEBUG=-all wine64 "C:/Program Files/BOC/ADOxx_1.8.0/adbinst.exe"
- Run a command like:
- In the dialog specify:
- the "Database name", which should be between 3 and 8 characters long and should only use ASCII letters and numbers,
- the "License number",
- select "SQLITE" as the "Database system",
- select "WITHOUT Single-Sign-on" for "Single-Sign-on installation option",
- mark "Create new database"
- Select "OK".
By default the database files are located in the folder %APPDATA%\ADOxx\sqlitedbs\
of the Wine-prefix. The environment variable ADO_SQLITE_DBFOLDER
(must be set in the Wine-prefix) can be used to specify a path to a different folder where the database files should be stored instead.
Some ADOxx based tools come with example models / Attribute Profiles. These are located in the adostd.adl
file inside the application's folder. After finishing the installation import them through the Modelling Toolkit by switching to the Import/Export component and selecting the menu Model -> ADL Import -> Models/Attribute profiles....
Create Shortcuts
The easiest way is to copy the provided shortcuts located in install-support/
into the /Applications/
folder. If necessary, adapt the scripts in the shortcuts as needed. These are located in the shortcuts under Contents/MacOS/start_toolkit.sh
.