[macruby-changes] [4456] MacRubyWebsite/trunk/content/realworld-dynamic-bundles.txt

source_changes at macosforge.org source_changes at macosforge.org
Tue Aug 24 09:14:08 PDT 2010


Revision: 4456
          http://trac.macosforge.org/projects/ruby/changeset/4456
Author:   mattaimonetti at gmail.com
Date:     2010-08-24 09:14:08 -0700 (Tue, 24 Aug 2010)
Log Message:
-----------
First portion of the Bundle tutorial for the MacRuby website

Added Paths:
-----------
    MacRubyWebsite/trunk/content/realworld-dynamic-bundles.txt

Added: MacRubyWebsite/trunk/content/realworld-dynamic-bundles.txt
===================================================================
--- MacRubyWebsite/trunk/content/realworld-dynamic-bundles.txt	                        (rev 0)
+++ MacRubyWebsite/trunk/content/realworld-dynamic-bundles.txt	2010-08-24 16:14:08 UTC (rev 4456)
@@ -0,0 +1,195 @@
+--- 
+title:      Real-world dynamic bundle creation
+created_at: 2010-08-08 23:41:08.125402 +01:00
+updated_at: 2010-08-08 23:41:08.125777 +01:00
+tutorial:   true
+author:     Nick Ludlam
+filter:
+  - erb
+  - textile
+--- 
+h1(title). <%= h(@page.title) %>
+
+<div class="author">
+  By <%= member_name(@page.author) %>
+</div>
+
+<div class='tutorial'>
+
+In this tutorial we will examine a real-world case of wanting to read ID3 tags from MP3 files in a quick and efficient manner from MacRuby. The solution must also be packagable, so we can build a stand-alone version of the application, free of any specific system dependencies.
+
+While there are some existing gems to read ID3 tags, the native Ruby implentation, <em>id3lib-ruby</em>, does not compile with the current version (0.6 as of this tutorial creation) of MacRuby, and the other gem (id3) complicates portability by wrapping a C library.
+
+To bring about a cleaner solution, we can take advantage of MacRuby's ability to load Objective-C bundles at runtime. The Objective-C layer of these bundles can be a very thin wrapper around native C or C++ calls, giving us a powerful flexibility to pull in any kind of compiled code we choose. In doing this, we can also ensure that the library is built as a fat binary, ensuring maximum compatibility with end users.
+
+h3. Preparation
+
+The framework chosen was one called TagLib (<a href="http://developer.kde.org/~wheeler/taglib.html">developer.kde.org/~wheeler/taglib.html</a>), which is a nicely clean and portable C++ implementation.
+
+Conveniently, a user on GitHub has already done some of the work for us in making an XCode project which builds a Framework of this library. After forking and cloning this Git project, we can start to build our Obj-C wrapper class around the library's functionality. We can get the basic Framework project set up with the following:
+
+<pre class="commands">
+git clone http://github.com/rahvin/TagLib.framework.git
+cd TagLib.framework
+wget http://developer.kde.org/~wheeler/files/src/taglib-1.6.3.tar.gz
+tar zxvf taglib-1.6.3.tar.gz
+mv taglib-1.6.3 taglib-src
+</pre>
+
+You can use the latest revision of TagLib, but this example will reference the 1.6.3 release.
+
+The last thing we need to do to the existing Framework target is add in the C wrapper functionality, which is an optional part of TagLib. We will utilise these C bindings later on, as they simplify the amount of code we need to write, and handle much of the UTF-8 string conversion for us.
+
+Select "Add to Project..." from the Project menu, and navigate to "taglib-src/bindings/c/", and add both "tag_c.cpp" and "tag_c.h". If you build the project at this stage, there should be no errors. So far, so good.
+
+h3. Adding our Bundle target
+
+The first thing we need to do is add a new Target to our project. Select "New Target..." from the Project menu, and select "Loadable Bundle". Call this <code>TagLibBundle</code>. 
+
+Open up the "Compile Sources" folder inside the "TagLib" Framework target. Shift-select every file in this folder, and open "Get Info" in the File menu. Open up the Targets tab at the top, and check the tickbox next to <code>TagLibBundle</code>. This ensures that every file used to compile the framework is also used to compile our new bundle target.
+
+Now open the <code>TagLibBundle</code> target info pane, and search for "Preprocessor Macros". Add <code>HAVE_CONFIG_H</code> to this entry. This is related to the way the project has been ported from the Autoconf setup of the original source code.
+
+!/images/realworld-dynamic-bundles/preprocessor_macros.png!
+
+While this info view is open, we also need to remove the entries under "Prefix Header"
+
+!/images/realworld-dynamic-bundles/remove_prefix_header.png!
+
+and "Other Linker Flags". These are set up by default, and are not required for our bundle.
+
+!/images/realworld-dynamic-bundles/remove_other_linker_flags.png!
+
+
+Now swap to the "General" tab and ensure that we are linking the project against the "Foundation" framework and "libz" shared library. Check that the project builds OK at this stage.
+
+h3. Adding our Objective-C wrapper class
+
+Now comes the fun part. We write a very simple Objective-C class to wrap the C functionality of the <code>TagLib</code> code.
+
+We will take a very simplistic approach in buidling the wrapper, as this ensures easy memory management. Our class will have an <code>initWithFileAtPath:</code> method, which we will use to initialise our class, and perform the scan of the file for tags. The tags themselves will be placed inside an <code>NSDictionary</code> to be read at a later point. Lastly the <code>dealloc</code> method will release the <code>NSDictionary</code>. All of the potentially tricky memory management is contained only within the <code>initWithFileAtPath:</code> method, and occurs within a single method invocation.
+
+Now we need to add an Objective-C class which will perform our wrapping duties. Add a new Objective-C file named "TagLib.m" to the project, subclassed from <code>NSObject</code>. Ensure that is is only part of the TagLibBundle target.
+
+!/images/realworld-dynamic-bundles/new_wrapper_class.png!
+
+
+Add a new Objective-C file to the <code>TagLibBundle</code> target called <code>TagLib.m</code>. Once we synthesize a simple <code>NSDictionary</code> to contain our tag, our header looks like:
+
+<% coderay :lang => 'c' do -%>
+ at interface TagLib : NSObject {
+    NSDictionary *tags;
+}
+
+ at property (nonatomic, retain) NSDictionary *tags;
+
+ at end
+<% end %>
+
+and our <code>TagLib.m</code> file:
+
+<% coderay :lang => 'c' do -%>
+ at implementation TagLib
+
+ at synthesize tags;
+
+- (id)init {
+    if (self = [super init]) {
+        self.tags = [NSDictionary dictionary];
+    }
+
+    return self;
+}
+
+- (void)dealloc {
+    [tags release]; tags = nil;
+    [super dealloc];
+}
+
+ at end
+<% end %>
+
+<% coderay :lang => 'c' do -%>
+
+- (id)initWithFileAtPath:(NSString *)filePath {
+  if (self = [super init]) {
+
+    // Our mutable dictionary for accumulation
+    NSMutableDictionary *tempDictionary = [NSMutableDictionary dictionary];
+
+    // Initialisation as per the TagLib example C code
+    TagLib_File *file;
+    TagLib_Tag *tag;
+    
+    // We want UTF8 strings out of TagLib
+    taglib_set_strings_unicode(TRUE);
+
+    file = taglib_file_new([filePath cStringUsingEncoding:NSUTF8StringEncoding]);
+
+    if (file != NULL) {
+      tag = taglib_file_tag(file);
+
+      // Collect title, artist, album, comment, genre, track and year in turn.
+      // Sanity check them for presence, and length
+      if (taglib_tag_title(tag) != NULL &&
+        strlen(taglib_tag_title(tag)) > 0) {
+        NSString *title = [NSString stringWithCString:taglib_tag_title(tag)
+                                             encoding:NSUTF8StringEncoding];
+        [tempDictionary setObject:title forKey:@"title"];
+      }
+      
+      if (taglib_tag_artist(tag) != NULL &&
+        strlen(taglib_tag_artist(tag)) > 0) {
+        NSString *artist = [NSString stringWithCString:taglib_tag_artist(tag)
+                                             encoding:NSUTF8StringEncoding];
+        [tempDictionary setObject:artist forKey:@"artist"];
+      }
+      
+      if (taglib_tag_album(tag) != NULL &&
+        strlen(taglib_tag_album(tag)) > 0) {
+        NSString *album = [NSString stringWithCString:taglib_tag_album(tag)
+                                             encoding:NSUTF8StringEncoding];
+        [tempDictionary setObject:album forKey:@"album"];
+      }
+      
+      if (taglib_tag_comment(tag) != NULL &&
+        strlen(taglib_tag_comment(tag)) > 0) {
+        NSString *comment = [NSString stringWithCString:taglib_tag_comment(tag)
+                                               encoding:NSUTF8StringEncoding];
+        [tempDictionary setObject:comment forKey:@"comment"];
+      }
+      
+      if (taglib_tag_genre(tag) != NULL &&
+        strlen(taglib_tag_genre(tag)) > 0) {
+        NSString *genre = [NSString stringWithCString:taglib_tag_genre(tag)
+                                             encoding:NSUTF8StringEncoding];
+        [tempDictionary setObject:genre forKey:@"genre"];
+      }
+      
+      // Year and track are uints
+      if (taglib_tag_year(tag) > 0) {
+        NSNumber *year = [NSNumber numberWithUnsignedInt:taglib_tag_year(tag)];
+        [tempDictionary setObject:year forKey:@"year"];
+      }
+      
+      if (taglib_tag_track(tag) > 0) {
+      NSNumber *track = [NSNumber numberWithUnsignedInt:taglib_tag_track(tag)];
+      [tempDictionary setObject:track forKey:@"track"];
+      }
+      
+      // Free up our used memory so far
+      taglib_tag_free_strings();
+      taglib_file_free(file);
+      
+    }
+
+    // Make immutable
+    self.tags = [NSDictionary dictionaryWithDictionary:tempDictionary];
+    [tempDictionary release];
+  }
+  
+  return self;
+}
+<% end %>
+
+</div>
\ No newline at end of file
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.macosforge.org/pipermail/macruby-changes/attachments/20100824/b53eb253/attachment.html>


More information about the macruby-changes mailing list