Using the Components in macOS and iOS

Introduction

The following step by step instructions will help you create your own project for macOS and iOS and configure the project to use our components. The components can be used in the following types of applications:

Cocoa Application

When using the macOS edition of the toolkit in your Cocoa application you will need to add the header files for each component being used as well as the library itself.

  1. In Xcode, from the project navigator create a new group called "IPWorks". This is just for organization.
  2. Right click on the group and select "Add Files to <Your Project>". Browse to the 'headers' folder of the IP*Works! Installation and select the .h file for the component(s) you want to use in your project.
  3. Next we need to configure the linker flags. In the "Build Settings" section for the project, scroll down to the "Other Linker Flags" setting (under "Linking"). Set the flags to -lz -lresolv
  4. The next step is to set the compiler language settings. In the "Build Settings" section of the project settings, find the "Apple LLVM compiler X.0 - Language" section and change the following settings:
    • Set C Language Dialect to C99 [-std=c99]
    • Set C++ Language Dialect to Compiler Default
  5. Next, the dynamic library needs to be linked. Navigate to the "Build Phases" section, expand "Link Binary With Libraries", add a new framework, and navigate with "Add Other" to the 'lib' folder of the product installation directory to select the .dylib file.
  6. Finally, the search paths must be set to the directory with the library linked in the previous step. In "Build Settings", find both "Library Search Paths" (under "Search Paths") and "Runpath Search Paths" (under "Linking") and add the path to the 'lib' folder where the .dylib file resides.
This is all that's necessary. After importing the appropriate header files you should be able to now code, build, and distribute your application like normal. Please see the demos included in the toolkit for examples using the components.

iOS Application

The steps for using /n software components in an iOS application are similar to those for a Cocoa application, as described below.

  1. In Xcode, from the project navigator create a new group called "IPWorks". This is just for organization.
  2. Right click on the group and select "Add Files to <Your Project>". Browse to the "headers" folder of the IP*Works! Installation and select the .h file for the component(s) you want to use in your project.
  3. Next we need to configure the linker flags. In the "Build Settings" section for the project, scroll down to the "Other Linker Flags" setting (under "Linking"). Set the flags to -lz -lresolv
  4. The next step is to set the compiler language settings. In the "Build Settings" section of the project settings, find the "Apple LLVM X.0 - Language" section and change the following settings:
    • Set C Language Dialect to C99 [-std=c99]
    • Set C++ Language Dialect to Compiler Default
  5. Next, the library needs to be linked. Navigate to the "Build Phases" section, expand "Link Binary With Libraries", add a new framework, and navigate with "Add Other" to the 'lib' folder of the product installation directory to select the .a file.
  6. In iOS applications the "libc++.dylib" file also needs to be linked. Note that this may be called "libc++.tbd" depending on your Xcode version. This should be linked with the same process as the previous step, though it should be included in the default library list without selecting "Add Other".
  7. Finally, the search paths must be set in "Build Settings". Find both "Library Search Paths" (under "Search Paths") and "Runpath Search Paths" (under "Linking") and add the path to the 'lib' folder where the .a file resides.
This is all that's necessary. After importing the appropriate header files you should be able to now code, build, and distribute your application like normal. See the demos included in the toolkit for examples using the components.

Swift support

The Red Carpet 2017 Vol. 4 Update brings support for Swift 4.0 to all of our components! Within the installation directory you will see a folder named "swift", which contains the wrappers necessary for using the components in Swift. To include the components in a project using Swift follow the steps below.

  1. Right click the project and select "Add files" to add the required files as below.
    • .h files. The header file for each component must be included, and are found in the 'headers' folder of the installation. For instance, IPWorksHTTP.h.
    • .swift files. The swift file for each component must also be included, and are found in the 'swift' folder of the installation. For instance, IPWorksHTTP.swift.
    • .dylib files (macOS Edition) or .a files (iOS Edition). The .dylib/.a files for the product must be added as well, and are found in the 'lib' folder of the installation. For instance, libipworks.16.0.dylib or libipworks.16.0.a.
  2. Now we need to add a bridging header file. This may happen automatically as you add the .h and .swift files to the project. If not, you'll need to do this manually by creating a new header file. In the project manager, go to "New File", select "Header File", and save it in the project directory. This can have any name, such as bridging_header.h, and it should include one import statement for each component header, like this:
    #import "IPWorksHTTP.h"
  3. Now, we'll need to configure a number of things in the project's "Build Settings" tab:
    • Go to the "Linking" section, find the "Other Linker Flags" setting, and set (or add) the flags -lz -lresolv.
    • For macOS Only: Still in the "Linking" section, for the "Runpath Search Paths" setting, add the path to the 'lib' folder where the .dylib file resides. Be sure to surround the path in double quotes if it has spaces.
    • Now, go to the "Swift Compiler - General" section and set the "Objective-C Bridging Header" setting to the bridging_header.h file created in the previous step.
    • Finally, go to the "Search Paths" section, find the "Library Search Paths" section, and add the path to the 'lib' folder where the .dylib or .a file resides. Be sure to surround the path in double quotes if it has spaces.
  4. Now, go to the project's "Build Phases" tab, and expand the "Link Binary With Libraries" section.
    • Ensure that the .dylib or .a file appears there (if it isn't, you can drag it there from the Project Navigator sidebar).
    • For iOS Only: You'll also need to add the libc++.tbd library; click the + button at the bottom of the section, search for libc++.tbd, and click "Add". (Note that, sometimes, XCode will only add the library to the "Frameworks" folder in the Project Navigator sidebar, but won't actually add it to the list of libraries to link to the binary. If that happens, simply drag it to the "Link Binary With Libraries" section manually.)

After these steps you should now be able to use the components in your Swift code. For example:

var http = IPWorksHTTPSwift()
do {
    try http.get("https://www.apple.com")
    var data = http.transferredData
    print(data)
} catch {
    print(error)
}


We appreciate your feedback.  If you have any questions, comments, or suggestions about this article please contact our support team at kb@nsoftware.com.