This is the installation manual for LIBPF™ SDK (LIBrary for Process Flowsheeting Software Development Kit) version 1.0 on Apple OS X operating systems, for the model developer who wants to install a LIBPF SDK she received, that has been packaged by a LIBPF core developer.

Mandatory prerequisites

LIBPF™ development on Apple OS X is supported on the following versions:

  • OS X Mavericks 10.9

  • OS X Yosemite 10.10

  • OS X El Capitan 10.11

To develop models with the LIBPF™ SDK, as a minimum you need:

  1. The C++ compiler / Integrated Development Environment (IDE), including the command line tools;

  2. A software package management system to install the required 3rd party software tools and libraries.

Compiler

The currently supported C++ compiler / IDE is Xcode versions:

  • 6.1.1 on OS X 10.9

  • 7.2.1 on OS X 10.10

  • and 7.3.1 on OS X 10.11

Alternatively you can use the compiler from Xcode, but Qt Creator as IDE - see instructions below.

Here are the steps to install Xcode:

  • OS X Mavericks 10.9:

    1. download the latest Xcode available for OS X 10.9, i.e. version 6.1.1, from https://developer.apple.com/ (you will need a valid Apple ID for that):

      Screenshot

    2. once the download of the Xcode_6.1.1.dmg file is complete (2.5 GB) double-click on it to mount it, then install Xcode by dragging the Xcode icon on the Applications folder link:

      Screenshot

  • OS X Yosemite 10.10:

    1. download the latest Xcode available for OS X 10.10, i.e. version 7.2.1, from https://developer.apple.com/ (you will need a valid Apple ID for that):

      Screenshot

    2. once the download of the Xcode_7.2.1.dmg file is complete (4.4 GB) double-click on it to mount it, then install Xcode by dragging the Xcode icon on the Applications folder link:

      Screenshot

  • OS X El Capitan 10.11: install the current Xcode (at the time of writing version 7.3.1) directly from the Mac App Store:

    Screenshot

warning: do not install an Xcode beta from https://developer.apple.com/xcode/download/ ! beta versions of Xcode are not supported.

Once Xcode is installed, launch it once (click on Launchpad, click on the Xcode icon), confirm that you want to start an application downloaded from the internet (this dialog will not appear if you got Xcode from the app store), accept the Xcode and iOS SDKs license agreement; then close Xcode.

Now install the Xcode command line tools:

  1. open a terminal window first: click on Launchpad, type "terminal", click on the Terminal icon:

    Screenshot

  2. Type in the terminal the command:

    xcode-select --install
    

    as in this screenshot:

    Screenshot

    then confirm the installation:

    Screenshot

    accept the Command Line Tools License Agreement:

    Screenshot

    and wait for the download / install to complete.

  3. verify the install of the Xcode command line tools by typing in the terminal:

    gcc -v
    

    expected output (for Xcode 7.3.1 on OS X En Capitan 10.11, may differ slightly for different versions):

    Configured with: --prefix=/Applications/Xcode.app/Contents/Developer/usr --with-gxx-include-dir=/usr/include/c++/4.2.1
    Apple LLVM version 7.0.2 (clang-703.1.31)
    Target: x86_64-apple-darwin15.6.0
    Thread model: posix
    

Package management

We need a software package management system to install the required 3rd party software tools and libraries.

While there are several package management systems available for OS X (such as Fink, MacPorts, etc.) and all of them should be fine, the supported package management system is Homebrew.

Install Homebrew according to the instructions on its homepage:

Screenshot

Once Homebrew is installed, type these commands in a terminal to install the required 3rd party software tools and libraries:

brew doctor
brew install --c++11 boost
brew install homebrew/science/suite-sparse
brew install boost-build jsoncpp libmxml swig xz

Note: the second command will take some time !

Optional prerequisites

Depending on your requirements, there are more tools you might need.

To run your models

If you plan to test and debug the developed models on the development workstation, you also need to install one of the LIBPF™ 1.0 demos, so that the installer will take care of installing the runtime prerequisites, setup the database and the ODBC / registry settings.

LIBPF™ must also be activated, see the LIBPF™ Activation Guide (English or Italian) for the rationale and the functioning of the activation system.

To keep your code under version control

If you wish to orderly manage the changes to the source code of your models you might want to put the code you write under a Version Control System (VCS); OS X has preinstalled the excellent command-line version of git, the leading distributed revision control system.

If you want to make your life easier you can install a GUI client, there are a few for OS X at this link.

To enhance the User Interface or just use Qt Creator

If you plan to modify the open-source User Interface for LIBPF™ (UIPF), or you just want to use the Qt Creator IDE, you will need the cross-platform application framework Qt.

Install the open source Qt offline installer (a stand-alone binary package including Qt libraries and Qt Creator) for OS X Host and for OS X targets (at the time of writing, version 5.6.0) from this link.

Get and install the LIBPF™ SDK

Once you have set up the prerequisites, download the LIBPF™ SDK from the link you have been supplied.

The LIBPF™ SDK comes in a xz compressed tar archive (such as LIBPF_SDK_osx_1.0.xxxx.tar.xz); use the OS X Archive utility to extract the tar.xz compressed archive.

The LIBPF™ SDK does not rely on absolute paths so you can move it to any location, such as on the Desktop, at your profile's root, on a removable volume etc.

Note: in the examples below, it is assumed the LIBPF™ SDK has been moved to the desktop in a directory named LIBPF_sdk.

Testing your LIBPF™ SDK install

The following procedures are for testing that the installation of the LIBPF™ SDK on OS X operating systems was successful.

LIBPF™ kernel

By default the SaltPepper example is supplied as test case with the LIBPF™ SDK.

The procedure to build and run it is different whether you use the command-line or one of the two Integrated Development Environments (IDEs) supported on OS X: Qt Creator or Xcode.

Command-line

Follow this procedure:

  • Open a terminal, then move to the LIBPF SDK location, for example:

    cd ~/Desktop
    cd LIBPF_sdk
    
  • enter the "pepper" sub-directory and compile the SaltPepper example with:

    cd pepper
    b2 install-bin
    
  • move to the bin directory and run it with:

    cd ../bin
    ./Qpepper new SaltPepper
    

Qt Creator as IDE

Install Qt then follow this procedure:

  • open the "pepper.pro" project file in the "pepper” directory by double-clicking

  • configure the project for Desktop Qt 5.x.0 clang 64 bit for both debug and release configurations, as in this screen-shot:

Screenshot

  • build the project (Build -> Build Project "pepper")

  • in the left-hand-side Tab "Projects" just under "Debug", then top tab "Running" set "new SaltPepper" as run arguments; also set LIBPF_sdk/bin as Working directory (this step is required to make sure the kernel find the SQlite database persistency.db)

  • run it (menu Build -> Run)

Note: occasionally (especially after a major Xcode upgrade) you may encounter this error in Qt creator:

Screenshot

Error while parsing file ...pro. Giving up.
Project ERROR: Xcode not set up properly. You may need to confirm the license agreement by running /usr/bin/xcodebuild.

in this case open a terminal, launch the /usr/bin/xcodebuild command prefixed by sudo and follow the instructions:

sudo /usr/bin/xcodebuild

Screenshot

Xcode as IDE

Install Qt then follow this procedure:

  • open a terminal in the "pepper” directory, then generate the project file with qmake:

    cd pepper
    /Qt/5.5/clang_64/bin/qmake -spec macx-xcode
    
  • this command will generate the “pepper.xcodeproj” Xcode project file in the "pepper” directory; open it with Xcode by double-clicking

  • build the project (Product -> Build)

  • click on the name of the "pepper" target in the drop-down menu next to Run and Stop, click on "Edit Scheme..." then on the arguments tab and type "new SaltPepper"; also set LIBPF_sdk/bin as custom Working Directory (this step is required to make sure the kernel find the SQlite database persistency.db)

  • run it (Product -> Run).

User interface for LIBPF™

Open a terminal, then move to the LIBPF SDK location, for example:

cd ~/Desktop
cd LIBPF_sdk

then clone the last version of UIPF from https://gitlab.com/simevo/UIPF:

git clone https://gitlab.com/simevo/UIPF.git

This command will create a UIPF directory in LIBPF_sdk.

In this UIPF folder double click on the UIPF.pro Qt Creator project file and set up the project:

  • Target Setup: Desktop

  • Create build configuration “Manually”

  • Use Shadow building

  • For each configuration set the ..\bin folder

  • Import build from ...\UIPF

  • Create Build Configuration: “None”

  • Projects – Run Setting: Add a run configuration with the executable path pointing to the folder containg uipf\bin\Debug.UIPF\uipf_debug.exe.

Then build the User Interface for LIBPF™.

How to get on

  1. For more information on how to use the LIBPF™ SDK see the LIBPF SDK manual and the LIBPF SDK reference

  2. Follow one of the Model Developer step-by-step tutorials

  3. Create a subfolder in LIBPF_sdk to put your own source code, adhering to the Source code directory structure standard, for example:

    cd LIBPF_sdk
    mkdir project123
    mkdir project123/src
    mkdir project123/include
    
  4. Start coding & have fun !