Flip Configuration Guide

Setting up Using gyp

This chapter explains how to set up your build environment using the gyp tool.

Overview

gyp, "Generate your project" is a tool made by Google which was made for the Chromium project their Google Chrome application. The tool allows to have a set of files in editable text format that can be used to generate automatically Windows Visual Studio or Apple XCode project.

This tool is used by the Flip framework in two ways :

gyp requires a proper installation of the python programming language to work.

The gyp system documentation is outside of the scope of this guide. More information on the gyp tool is available here.

configure.py
flip.gyp
flip_lib.gpyi
flip_src.gpyi
src/
   src.gpyi
test/
   test.gypi
   win.gypi
   xcode.gypi

The following section will describe the purpose of every gyp and gypi file.

Top Level Files

configure.py

While not a gyp file, configure.py is a python file used to produce projects for regression and performance testing. It requires an installation of python 2.7 or greater.

Executing this python script will create a projects folder at the top level and will put all required files to build and run tests.

flip.gyp

flip.gyp is a top level gyp file that produces all the test targets to test the Flip framework.

flip_lib.gypi

flip_lib.gypi is a top level gypi file. When integrating the Flip framework to your build system, this is typically the only file to include.

It will add all source and header files to integrate the Flip framework core and contribution files. It will also set up the include path and makes sure that every dependent target have their include path correctly setup.

Important: If including this file to your build system generate errors for XCode, please make sure to read the Troubleshooting XCode header inclusion

flip_src.gypi

flip_src.gypi is a top level gypi file. In contains only all source and header files and set up include path accordingly.

Important: If including this file to your build system generate errors for XCode, please make sure to read the Troubleshooting XCode header inclusion

src Files

src.gypi

src/src.gypi contains only the source and header files of the Flip framework core and contribution.

Important: If including this file to your build system generate errors for XCode, please make sure to read the Troubleshooting XCode header inclusion

test Files

The gypi files in test are only used for regression and performance tests. They are typically not included in your build environment. However they provide a reference for specific configuration, for example to set up dynamic library linkage.

test.gypi

test.gypi contains all targets to produce all tests.

win.gypi

win.gypi contains all specific Windows Visual Studio project options. It provides debug and release as well as 32-bit and 64-bit configurations.

It provides the only dependency of Flip, which is Winsockets 2 ws2_32.lib.

Finally it contains the set of disabled warnings necessary for the Flip framework to compile without any kind of warning :

xcode.gypi

xcode.gypi contains all specific Apple XCode project options. It provides debug and release as well as 32-bit and 64-bit configurations.

Troubleshooting XCode header inclusion

The default XCode header inclusion rule specifies that headers added to the project will be searched directly. This means that the Document.h file could be accessed as :

#include "Document.h"

instead of :

#include "flip/Document.h"

This is problematic on platforms where the HFS filesystem is specified as case insensitive. In this case system header files including for example float.h will use flip/Float.h instead.

On MacOS X, the issue arrises for flip/Float.h and flip/Signal.h.

To overcome this problem, the Flip user developer will have to explicitely tell XCode not to search those files by specifying USE_HEADERMAP to NO.

More information on this matter is available here.

An example of this setting can be find in the top level flip.gyp file :

'xcode_settings': {
   'USE_HEADERMAP': 'NO',
},