fltk/README.macOS.md

README.macOS.md - Building FLTK under Apple macOS

Contents

• Contents

• Introduction

• How to Build FLTK using CMake AND Xcode

  • Prerequisites
  • Downloading FLTK and Unpacking
  • Configuring FLTK
  • Building FLTK
  • Testing FLTK
  • Installing FLTK
  • Creating new Projects

• How to Build FLTK using CMake and make

  • Prerequisites
  • Downloading FLTK and Unpacking
  • Configuring FLTK
  • Building FLTK
  • Testing FLTK
  • Installing FLTK
  • Creating new Projects

• How to Build FLTK Using autoconf and make

  • Prerequisites
  • Downloading FLTK and Unpacking
  • Configuring FLTK
  • Building FLTK
  • Testing FLTK
  • Installing FLTK
  • Creating new Projects

• Make an Application Launchable by Dropping Files on its Icon

• Document History

Introduction

FLTK supports macOS version 10.3 Panther and above. At the time of writing (Jan. 2019), FLTK compiles and runs fine on the most recent macOS 10.14 Mojave.

FLTK 1.4 supports the following build environments on the macOS platform:

• cmake and Xcode, no shell needed
• cmake and make from the command line
• autoconf and make from the command line

All environments will generate Unix style static libraries and macOS style app bundles.

How to Build FLTK Using CMake and Xcode

This option is best for users who like to develop their apps using Apple's Xcode IDE. There is no need to ever use a command line shell in this configuration.

This option requires an Apple ID and administrator rights.

Prerequisites (CMake, Xcode)

In order to build FLTK, you need to install CMake and Xcode.

"CMake is used to control the software compilation process using simple platform and compiler independent configuration files, and generate native makefiles and workspaces that can be used in the compiler environment of your choice."

Please download and install the Mac OS X version of CMake from www.cmake.org. Download the .dmg file, click it, and when the Finder window opens, drag the CMake icon into the Applications folder.

Xcode can be downloaded via the App Store. You will need an Apple ID and administrator right for this. Installing Xcode will take well over an hour.

Downloading and Unpacking (CMake, Xcode)

FLTK 1.4 is currently (as of Jan. 2019) only available as a source code repository via GitHub. You will need to clone the repository to check out the source code onto your machine. This has the great benefit that the source code can be updated later simply by telling git to pull the newest release.

If you want to use Xcode to clone the FLTK GitHub repository, you will have to set up a GitHub Account in the Xcode preferences. If you don't have a GitHub account, or don't want to create one for Xcode, you can use still the command line git clone https://github.com/fltk/fltk.git fltk-1.4.git to ceck out the repo.

Start Xcode. Select Source Control >> Clone... in the main menu.

A dialog box will open with a search field and a list of repositories. Enter fltk/fltk in the search field. A list of matchin repositories appears. The first one should be named fltk and be owned by fltk. Select it and click Clone.

A file chooser appears. Navigate to your home directory. The create a new folder named dev. Enter fltk-1.4.git in the Save As: field and click Clone, then Done in the previous dialog.

The local copy of your repository can be updated by loading it into Xcode and selecting Source Control >> Pull... in the main menu.

Configuring FLTK (CMake, Xcode)

Launch CMake by pressing Command+Spacebar, the type CMake and press return. CMake should open with a large dialog box.

The first input field is labeled with Where is the source code: . Click on Browse Source... and navigate to your home folder, then dev, then fltk-1.4.git. Click Open.

The next input field is marked Where to build the binaries:. Click Browse Build... and navigate to your home folder, then dev, then fltk-1.4.git, then use New Folder to create a folder named build, and inside that, create a folder named Xcode. Click Open.

The top two input fields should read

/Users/your_name/dev/fltk-1.4.git

and

/Users/your_name/dev/fltk-1.4.git/build/Xcode

Back in the CMake main window, click Configure, select Xcode as the generator and click Done. CMake will now analyse your system and find tools and dependencies. When done, the upper list field in CMake will show CMAKE, FLTK, and OPTION. Open the OPTION field and find the entries OPTION_USE_SYSTEM_LIBJPEG and OPTION_USE_SYSTEM_LIBPNG, and disable both for maximum compatibility with other macOS installation.

Finally, click Generate to generate the Xcode IDE file.

You may be wondering why we chose this rather involved way of creating the IDE files instead of just including the IDEs in the repo. Well, we did for the longest time, but creating new IDEs for every possible platform is quite involved. IDE file formats change, platforms change, and FLTK changes as well, and maintenance of the IDEs had become a nightmare. CMake on the other hand is very smart, knows about platforms and IDEs that we could never support manually, and usually needs to be run only once. Even when updating the FLTK source code later, CMake will be smart enough to update the build files as well.

Building FLTK (CMake, Xcode)

Now this is easy if all the previous steps were successful. If you are still in CMake, just click Open Project and CMake will launch XCode for you. If not, just launch XCode and open Macintosh HD⁩ ▸ ⁨Users⁩ ▸ your_name⁩ ▸ ⁨dev⁩ ▸ ⁨fltk-1.4.git⁩ ▸ ⁨build⁩ ▸ ⁨Xcode⁩ ▸ ⁨FLTK.xcodeproj.

XCode may or may not ask to Autocreate Schemes. Click Automatically Create Schemes.

In Xcode, set the 'active Scheme' to 'hello' or any other test program and press CMD+R to compile and run that application.

Testing FLTK (CMake, Xcode)

After a successful build, you can test FLTK's capabilities by choosing 'ALL_BUILD' as the 'active Scheme' and pressing CMD+B to build, then choosing 'demo' and pressing CMD+R to run the demo program.

TODO: as of Jan 2019, compiling 'demo' will not compile any of the other demo programs. We really have to update the dependencies!

Installing FLTK (CMake, Xcode)

TODO: choosing the target 'INSTALL' will not work at this point because it requires root permission.

Creating new Projects (CMake, Xcode)

TODO: we still need to write a simple CMake file for creating a minimal cross platform app.

How to Build FLTK Using CMake and make

This option is best for users who like to develop their apps without using Apple's Xcode IDE, but like the advantages of CMake over autoconf. Users should be comfortable with using bash or tcsh in a terminal window.

This option requires neither administrator rights, nor an Apple ID.

Prerequisites (CMake, make)

In order to build FLTK, you need to install CMake and the Xcode command line tools.

"CMake is used to control the software compilation process using simple platform and compiler independent configuration files, and generate native makefiles and workspaces that can be used in the compiler environment of your choice."

Please download and install the Mac OS X version of CMake from www.cmake.org. Download the .dmg file, click it, and when the Finder window opens, drag the CMake icon into the Applications folder.

We will be using CMake from the command line. Please launch CMake and choose Tools > How to Install for Command Line Use and follow the instructions in the dialog box. If you have admin right, you can also use

sudo ln -s /Applications/CMake.app/Contents/bin/cmake /usr/local/bin/cmake

Installing the Xcode command line tools is pretty straight forward. Just enter this in your shell and follow the dialogs:

xcode-select --install

On older versions of macOS, you will have to install Xcode from the App Store and then install the command line tools from within Xcode.

Downloading and Unpacking (CMake, make)

Downloading FLTK is explained here.

Configuring FLTK (CMake, make)

Using you shell in the terminal, make sure that you are in the root directory of your FLTK source code tree.

Create a directory where all FLTK binaries will be built:

mkdir build
cd build
mkdir Makefile
cd Makefile

Now configure your FLTK installation:

cmake -G "Unix Makefiles" \
    -D OPTION_USE_SYSTEM_LIBJPEG=Off \
    -D OPTION_USE_SYSTEM_ZLIB=Off \
    -D OPTION_USE_SYSTEM_LIBPNG=Off \
    ../..

CMake runs a number of tests to find external headers, libraries, and tools. The configuration summary should not show any errors. You can now continue to build FLTK.

For the advanced user, there are a few more optinons to the CMake setup. Type cmake -L ../.. to get a complete list of options. These should be pretty self-explanatory. Some more details can be found in online documentation.

Building FLTK (CMake, make)

Now this is easy if all the previous steps were successful. Stay in your build/Makefiles directory and type:

make

The entire FLTK toolkit including many test programs will be built for you. No warnings should appear, but "ranlib" may complain about a few modules having no symbols. This is normal and can safely be ignored.

Testing FLTK (CMake, make)

After a successful build, you can test FLTK's capabilities by running

open bin/examples/demo.app

Installing FLTK (CMake, make)

If you did not change any of the configuration settings, FLTK will be installed in /usr/local/include, /usr/local/lib, and /usr/local/bin by typing

sudo make install

It is possible to install FLTK without superuser privileges by changing the installation path to a location within the user account by adding the --prefix=PREFIX parameter to the ./configure command.

Creating new Projects (CMake, make)

FLTK provides a neat script named fltk-config that can provide all the flags needed to build FLTK applications using the same flags that were used to build the library itself. Running fltk-config without arguments will print a list of options. The easiest call to compile an FLTK application from a single source file is:

fltk-config --compile myProgram.cxx

fltk-config and our user interface designer fluid will be installed in /usr/local/bin/ by default. I recommend that you add this directory to the shell PATH variable.

How to Build FLTK Using autoconf and make

This option is best for users who like to develop their apps without using Apple's Xcode IDE and prefer minimal dependencies of a Makefile over CMake. Users should be comfortable with using bash or tcsh in a terminal window.

This option requires administrator rights, but no Apple ID.

Prerequisites (autoconf, make)

In order to build FLTK from the command line, you need to install a C++ compiler environment, make and autoconf. Installing the Xcode command line tools is the easiest way to get all prerequisites in one simple step.

Launch Terminal.app by pressing Command+Spacebar and typing Terminal and pressing return. I like to keep the Terminal in the Dock for future use (launch Terminal, right-click or control-click on the Terminal icon that is now in the docking bar, and choose Options->Keep in Dock).

Installing the Xcode command line tools is pretty straight forward. Just enter this and follow the dialogs:

xcode-select --install

On older versions of macOS, you will have to install Xcode from the App Store and then install the command line tools from within Xcode.

Apple no longer includes autoconf in the Xcode command line tools. To install autoconf, we first need to installe brew by typing this rather cryptic command in the shell you will need the root password):

ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

After a few minutes, we can now build and install all other tools from one simple command:

brew install autoconf automake

Downloading and Unpacking (autoconf, make)

FLTK 1.4 is currently (as of Jan. 2019) only available as a source code repository via GitHub. You will need to clone the repository to check out the source code onto your machine. This has the great benefit that the source code can be updated later simply by telling git to pull the newest release.

Start your terminal. If you have not set up a developer directory yet, I recomment to use ~/dev and put all your projects there:

# make sure we are in the home directory
cd ~
# create our developer directory and go there
mkdir dev
cd dev

Now create a copy of the source code archive at Github on your local file system:

git clone https://github.com/fltk/fltk.git fltk-1.4.git
cd fltk-1.4.git

Configuring FLTK (autoconf, make)

Using you shell in the terminal, make sure that you are in the root directory of your FLTK source code tree.

If you are configuring fltk for the first time, you need to instruct FLTK to create some very basic configuration files. Type:

NOCONFIGURE=1 ./autogen.sh

This script may generate a few error messages which you can sefely ignore.

Now configure your FLTK installation. Stay in your FLTK source-code directory and type

./configure

The configuration script runs a number of tests to find external headers, libraries, and tools. The configuration summary should not show any errors. You can now continue to build FLTK.

For the advanced user, there are a few more optinons to the configure script. Type ./configure --help to get a complete list of options. These should be pretty self-explanatory. Some more details can be found in online documentation.

Building FLTK (autoconf, make)

Now this is easy if all the previous steps were successful. Stay in your FLTK source-code directory and type:

make

The entire FLTK toolkit including many test programs will be built for you. No warnings should appear, but "ranlib" may complain about a few modules having no symbols. This is normal and can safely be ignored.

Testing FLTK (autoconf, make)

After a successful build, you can test FLTK's capabilities by running

test/demo

Installing FLTK (autoconf, make)

If you did not change any of the configuration settings, FLTK will be installed in /usr/local/include, /usr/local/lib, and /usr/local/bin by typing:

sudo make install

It is possible to install FLTK without superuser privileges by changing the installation path to a location within the user account by adding the --prefix=PREFIX parameter to the ./configure command.

Creating new Projects (autoconf, make)

FLTK provides a neat script named fltk-config that can provide all the flags needed to build FLTK applications using the same flags that were used to build the library itself. Running fltk-config without arguments will print a list of options. The easiest call to compile an FLTK application from a single source file is:

cat << EOF > main.cxx
  #include <FL/Fl_Window.H>
  int main(int argc, char **argv) {
    Fl_Window *win = new Fl_Window(600, 400, "Hello, world!");
    win->show(argc, argv);
    return Fl::run();
  }
EOF
fltk-config --compile main.cxx
./main

fltk-config and our user interface designer fluid will be installed in /usr/local/bin/ by default. I recommend that you add this directory to the shell PATH variable.

Make an Application Launchable by Dropping Files on its Icon

TODO: update for FLTK 1.4

• Prepare an Info.plist file for your application derived from file test/editor-Info.plist which allows any file to be dropped on the application icon. You can edit this file in Xcode and change Document types/Item 0/CFBundleTypeExtensions/Item 0 from the current "*" to the desired file extension. Use several items to declare several extensions.

• Call fl_open_callback() at the beginning of your main() function that sets what function will be called when a file is dropped on the application icon.

• In Xcode, set the "Info.plist File" build setting of your target application to the Info.plist file you have prepared.

• Rebuild your application.

Links

GitHub, git, forking, fetching. and pull requests

DOCUMENT HISTORY

• Oct 29 2010 - matt: removed warnings
• Oct 24 2010 - matt: restructured entire document and verified instructions
• Dec 19 2010 - Manolo: corrected typos
• Dec 29 2010 - Manolo: removed reference to AudioToolbox.framework that's no longer needed
• Feb 24 2011 - Manolo: architecture flags are not propagated to the fltk-config script.
• Apr 17 2012 - matt: added Xcode4 documentation
• Nov 13 2012 - Manolo: added "MAKE AN APPLICATION LAUNCHABLE BY DROPPING FILES ON ITS ICON"
• Apr 28 2014 - Manolo: how to build programs that run on various Mac OS X versions
• Mar 18 2015 - Manolo: removed uses of the Xcode3 project
• Apr 01 2016 - AlbrechtS: corrected typo, formatted most line breaks < 80 columns
• Dec 04 2018 - AlbrechtS: fix typo (lowercase fluid.app) for case sensitive macOS
• Dec 28 2018 - Matt: complete rework for FLTK 1.4