Appearance

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):

  1. Download the .zip package with the files for macOS from the ADOxx homepage.
  2. Extract the downloaded .zip file to a location of your choice.
  3. Open the .dmg file from the extracted location to mount the file and open the package.
  4. Drag and drop the ADOxx application into the "Applications" folder.
    macOS .dmg screen
  5. Unmount the .dmg file.
  6. 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.

  7. Select "ADOxx 1.8.0 Development Toolkit" in the pop-up. When started the first time a pop-up will inform of additional dependencies.
    macOS install further prerequisites
  8. Confirm the message and step through the process in the terminal window.
    macOS further installation in 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):

  1. Download the .zip package with the expert installation files for macOS from the ADOxx homepage.
  2. Extract the downloaded .zip file to a location of your choice.
  3. Open a terminal window and navigate to the extracted location.
  4. 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.
  5. Follow the instructions of the installation script.
    macOS further installation in terminal window
    • 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):

  1. Move the ADOxx application from the "Applications" folder to the recycle bin.
  2. (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):

  1. Open a terminal window and navigate to the of the installer files (extracted location for installation).
  2. 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.
  3. 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:

  • Wine: Necessary to run the Windows applications.
  • Homebrew: Necessary to install and manage Wine.

Additionally the tool requires a database to store the data:

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:

  1. Install necessary dependencies.
  2. Install the database management system.
  3. Create a Wine-prefix.
  4. Copy the ADOxx application files.
  5. Set up the ADOxx database.
  6. 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 ​

  1. 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.
  2. 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.

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 ​

  1. 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

Copy ADOxx Application Files ​

  1. Extract the contents of the .zip file containing the built ADOxx files, for example install-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\").
  2. 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 ​

  1. 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"
  2. 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"
  3. 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"
      adbinst.exe screenshot
  4. 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.