Tag Archives: app

How to Make a Build Script for Bundling dylib Files into an OS X App

Posted on by

Although I’m not new to Mac development I never needed to embed a dynamic library (.dylib file) into an app until just recently. Needless to say I struggled with this for a while.
I also wasn’t able to locate any single, up to date and reputable tutorial on the topic so I wanted to collect the bits and pieces I found into this single, easy to understand article so I could help others.

The strategy that worked for me, and which I’ll cover below, was to create a post-build script.

 

Understanding Dynamic Libraries

Dynamic libraries have encoded within them a “name” which actually serves as a path by which they are located. In order for your already built app to reference a dynamic library it needs to know where to find it and during the build process this encoded name becomes that location. When your app starts up it attempts to load all its dependencies at their named paths and unless said dynamic library is installed on the user’s Mac the app will crash.

Of course you can never be 100% certain a user will have the dynamic library beforehand and installed at just the right location. It therefore makes more sense to bundle the library within your app.

Determining the Encoded Name

In your app’s main target create a post-build script and enter the commands below, replacing MyProject with the name of your project and the “ThirdParty/Abc/” with the path of the .dylib file relative to your project’s base path.

echo OTOOL BEGIN\n
otool -L MyProject/ThirdParty/Abc/Abc.dylib\n
echo OTOOL END

Now build your project and inspect the build log (Right click on any build issue and select the “Reveal in Log” menu item). The output from otool’s execution should appear below “OTOOL BEGIN” and above “OTOOL END”.

Did it work? Okay, now remove these 3 lines from your build script but keep the dynamic library’s name handy for the last step.

 

Overriding the Dynamic Library’s Encoded Name

The below command overrides the dynamic library’s name to one that will match its path within your app’s folder (remember an OS X app is really an .app folder, not a file). Typically libraries appear under the “Frameworks” folder. NOTE: Make sure you have a “Copy Files” build phase which will copy the file from its source to this “Frameworks” folder by specifying it as the Destination.

install_name_tool -id @executable_path/../Frameworks/Abc.dylib MyProject/ThirdParty/Abc/Abc.dylib

NOTE: The executable path variable is the folder in which the true binary executable is located. Typically in the PRODUCT_NAME/Contents/MacOS folder. So the path @executable_path/../Frameworks/ is really PRODUCT_NAME.app/Contents/Frameworks.

In the above command replace Abc.dylib with your dynamic library’s filename.
Also replace MyProject with the name of your project.
In this example the source folder for the Abc.dylib is under “ThirdParty/Abc” and you’ll need to provide an appropriate path to your dylib file, following your project’s conventions.

Now that the dynamic library’s new encoded name matches the new location in the “Frameworks” folder the next step is to tell your app to expect it there.

Remember this is a post build step. Your app was originally linked against the not yet renamed dynamic library and thinks it needs to look for it there still. This is where we use the encoded name otool reported to us…

 

Modifying the App’s Reference to the Dynamic Library

The below command changes the referred location of the dynamic library from its original path to its new one within the “Frameworks” folder.  Add it to the bottom of your script.

install_name_tool -change usr/lib/Abc.dylib @executable_path/../Frameworks/Abc.dylib MyProject/ThirdParty/Abc/Abc.dylib

As with the previous step, modify the paths to reflect those of your project and take special careful to type all paths accurately.  The above “usr/lib” path may differ from that of your dylib and this is why you used otool.  Take the path you discovered with that tool and if different from “usr/lib” replace it.

Run the build once more. If no errors occur and the dylib file is indeed bundled in the “Frameworks” folder (you can check by stripping the .app extension from the folder) there is one last thing to test. Running the app!


Run It

Archive the project (Xcode menu Product → Archive). This will open the Organizer window. From here you can press the Distribute button which will prompt you for the method of distribution.
Choose “Export as Application” and export it to your desktop. The app is now waiting for you there and you only need to double click it. If the app starts up without complaint you’ve successfully bundled the dynamic library!

If the app doesn’t execute, check the error report OS X offers in the crash dialog to see what file path it expected to use. You can also reuse the otool command shown in the first step at the bottom of your build script to double check that the dynamic library was indeed renamed.  Most errors end up being mistyped paths and otool can prove so.

Agent App – How To Prevent A Mac App Icon From Appearing On The Dock

Posted on by

If you’re developing a Mac app that runs in the background most of the time (in other words an agent app) you typically don’t want to your app’s icon to consume space on the dock.

Luckily for us, achieving this is quite trivial.  Just follow these steps…

  1. In Xcode (4.3 for the purposes of this post), open the Project Navigator (the folder tab under the Run button).
  2. Select your project (the parent item with the blue print icon).  This opens the project details view.
  3. In the project details view select your app’s main target (under TARGETS) and select the Info tab.
  4. If it is not already present add an ‘Application is agent (UIElement)’ item under Custom Mac OS X Application Target Properties.
  5. Set this item’s value to YES (as shown below).

Application Is Agent

 

And you’re done!

From now on, whenever you execute your app its icon will no longer appear on the Dock or in the Alt + Tab application switcher.

When To Localize Your iPhone App

Posted on by

In the past I’ve highlighted some software design mistakes made by others and today I want to point the finger at myself and talk about a mistake I made in localizing my first iPhone app KEYBOX.  It is my hope that this article will help others avoid the same pitfalls I experienced.

I made KEYBOX to scratch a personal itch (digital privacy) and it was first released in 2005 as a J2ME app for Vodafone Japan’s market.As such it was never localized to any language other than Japanese.  That all changed this year when I ported it to iOS.  As the App Store is an international affair I naturally would like KEYBOX to benefit as many people as possible.  The main barrier to this is of course language.

For release 1 I decided to localize KEYBOX into the 4 languages with which I am familiar: English, French, Japanese and Spanish.

I now believe doing so this early was a huge mistake as it introduced two issues for me: serious delays in releasing and numerous layout changes.

In localizing KEYBOX, I underestimated the amount of effort it would take.  There are over 200 text snippets to translate from English.  Using online dictionaries to double check my translations and searching for real-world instances of each text snippet before issuing the final check of approval for each takes upwards of 20 hours for each language.  When you’re only doing this on the side (weekends and some evenings) you can imagine how much it delays the release of your app, which is otherwise feature complete and ready to go.

And then there was the EULA!  KEYBOX is unique in that it requires a rather lengthy EULA to protect myself from users who might be less than responsible with it.  Writing the English version was an experience in its own right.  Writing it in Japanese would’ve been a train wreck without help from my loving wife (also Japanese) and it took over 30 hours spread across 3 weeks.

An interesting surprise was that people in countries whose languages are not yet supported still download KEYBOX, and in droves!  Italy is perhaps one of the biggest markets and KEYBOX isn’t even in Italian yet.  I don’t know if support for Spanish and French is what makes this possible (the Romance language connection?) as KEYBOX is about privacy and I don’t solicit my users for such information.  While I’m sure that supporting multiple languages opens the door to more people enjoying my app, having so many languages supported from version 1 is perhaps less important than I initially thought.

Now to the issue of layout…  In comparison to English, Japanese can be an extremely compact language and most words are only 2 kanji characters in length.  And then there are French and Spanish whose words tend to be much longer than their English counterparts.  This naturally leads to sentences that expand and contract in length depending on the user’s locale.

Before translating the text I was tempted to avail myself of iOS’ ability to auto-adjust font sizes for a statically sized label.  I figured the sentence length wouldn’t vary so much and that an auto-adjusting font size could handle that difference.

I could not have been more wrong.  Doing so resulted in text so small that it was rendered unreadable and sometimes text that gets clipped off by the boundaries of the container label.

I learned, the hard way, that multilingual apps really are better off having multi-line labels with a fixed font size.

Going multiline however introduces a new problem.   It forces us to position controls spaced far enough from each other to compensate for the wordiest languages whose labels will expand the most.  Release 1 of KEYBOX followed this approach.  It worked for the most part but it took a lot of manual testing across languages to make sure the text was readable and that there were no overlapping elements.

I knew that I couldn’t take this approach forever and for release 2 I decided to change tactics.  I developed a high-level, goal-oriented layout utility class that lets me accomplish tasks such as “place this text field 10px under that label and center it on screen” or “left align this label 5px to the right of that icon”.  As a result I no longer have to consider the pixel locations of positionable elements across all locales at once and can focus more on the general look of the UI.  In some ways it works like HTML with the end result being one element following the last but unlike HTML it still retains simple, pixel perfect control.

 

Example:

KEYBOX 1 Without Dynamic Layout

KEYBOX 1 – Without Dynamic Layout

 

Keybox 2 import export

KEYBOX 2 – With Dynamic Layout (Text is directly under cloud image and the warning icon is to the left of the text)

 

I intend to open source this layout engine for those who want to maintain a professional layout for their multilingual apps but my best piece of advice would be to release one language at a time and just get your app out there first!  From there on, you can roll out new languages gradually.