You have multiple options available for integrating DTCoreText into your own apps. Ranked from most to least convenient they are:
DTCoreText is designed to be included as static library from a subproject, it embeds several classes from the DTFoundation project. If you want to use DTFoundation as well in your project you need to use the “Static Library (no DTFoundation)” target to avoid duplicate symbols.
GitHub offers tar balls for the individual tagged versions but you shouldn’t try to set these up with your project because those are missing the external references. Doing a recursive clone insures that you get all the files from all involved GitHub repositories.
DTCoreText needs a minimum iOS deployment target of iOS 4.2 because of:
- GCD-based threading and locking
Support for OS X is currently being developed.
Integrating via Cocoapods
Having set up Cocoapods you add DTCoreText to your
Podfile like this:
platform :ios pod 'DTCoreText'
This always gets the latest version of the pod spec from the global repository. It also automatically resolves the DTFoundation reference.
Cocoapods works by copying all source files into an Xcode project that compiles into a static library. It also automatically sets up all header search path and dependencies.
One mild disadvantage of using Cocoapods is that you cannot easily make changes and submit them as pull requests. But generally you should not need to modify DTCoreText code anyway.
Integrating via Sub-Project
This is the recommended approach as it lets Xcode see all the project symbols and dependencies and also allows for execution of the special build rule that processes the
default.css file into a link-able form.
If you use
git as SCM of your apps you would add DTCoreText as a submodule, if not then you would simply clone the project into an Externals sub-folder of your project. The repo URL can either be the one of the master repository or - if you plan to contribute to it - could be a fork of the project.
Getting the Files
The process of getting the source files of DTCoreText differs slightly whether or not you use
git for your project’s source code management.
As Git Submodule
You add DTCoreText as a submodule:
git submodule add https://github.com/Cocoanetics/DTCoreText.git Externals/DTCoreText
DTCoreText has several dependencies into the DTFoundation project. To have git clone the main project and also set up the dependencies do this:
git submodule update --init --recursive
Now you have a clone of DTCoreText in Externals/DTCoreText as well as a clone of DTFoundation in Externals/DTCoreText/Core/Externals/DTFoundation.
As Git Clone
If you don’t use git for your project’s SCM you clone the project into the Externals folder:
git clone --recursive https://github.com/Cocoanetics/DTCoreText.git Externals/DTCoreText
Now you have a clone of DTCoreText in
Externals/DTCoreText as well as a clone of DTFoundation in
You want to add a reference to
DTCoreText.xcodeproj in your Xcode project so that you can access its targets. You also have to set the header search paths, add some framework/library references and check your linker flags.
Adding the Sub-Project
Open the destination project and create an “Externals” group.
Add files… or drag
DTCoreText.xcodeproj to the Externals group. Make sure to uncheck the Copy checkbox. You want to create a reference, not a copy.
Add the following to your application target’s Build Phases, under Link Binary With Libraries:
- libDTCoreText.a (target from the DTCoreText sub-project)
Adding libDTCoreText creates an implicit dependency. That means if you are building your app and there is no current lib then Xcode would build it first.
You can move all the additional framework and library links that Xcode adds into your frameworks group.
Setting up Header Search Paths
For Xcode to find the headers of DTCoreText add
Externals/DTCoreText/Core to the User Header Search Paths. To find the headers of DTFoundation referenced by DTCoreText you also need to add
Externals/DTCoreText/Externals/DTFoundation/Core. Make sure you select the Recursive check box on both.
Setting Linker Flags
For the linker to be able to find the symbols of DTCoreText, specifically category methods, you need to add the
-ObjC linker flag:
In Xcode versions before 4.6 you also needed the
-all_load flag but that appears to no longer be necessary.
DTCoreText uses the
DTCoreTextFontOverrides.plist to speed up font matching. The version in the Demo App resources has the commonly used font families set up so that it can quickly get the name of a specific font face given font family and the italic and bold settings. It works without this as well, but will be slower. Add your own custom fonts to the plist and include it in your app to make use of this optimization.
default.css stylesheet that is used for defining the default HTML CSS styles is compiled into
default.css.h via a build rule. It is linked into the static library, so you don’t need to do anything there. If you want to customize something then please do so via the parse options documented in the NSAttributedString HTML Category.
At this point your project should build and be able to use DTCoreText functionality. As a quick Smoke Test - to see if all is setup correctly - you can test your setup by adding this code to your app delegate:
#import "DTCoreText.h" NSString *html = @"<p>Some Text</p>"; NSData *data = [html dataUsingEncoding:NSUTF8StringEncoding]; NSAttributedString *attrString = [[NSAttributedString alloc] initWithHTMLData:data documentAttributes:NULL]; NSLog(@"%@", attrString);
You should see that this executes and that the NSLog outputs a description of the generated attributed string.
Integrating via Framework
There are two framework targets available in the project:
- Static Framework - This is the static universal framework for use with iOS apps
- Mac Framework - This is a dynamic framework for use with Mac apps
Both include the headers and when adding them to a project Xcode should set up the header search path accordingly.