Unfortunately, traditional means of discovery have been increasingly tainted by commercialism. Thankfully, the Net is a big place with lots of great alternatives. One podcast that I'd like to recommend is NPR's All Songs Considered with Bob Boilen. I can't say I agree with all of his choices, but a few have been bang on. As a tribute to this new find, I'm finally updating my current listening list:

• Asobe Seksu - Transparence
• Alistar Blaik Bundale - The Day
• The Gaslight Anthem - The '59 Sound
• Mesmer - Teenage Dreams
• White Lies - Taxidermy
• Gooseflesh - Still Wild
• Bad Lieutenant - Sink or Swim
• 5 Cent Theatre - Shifting Sands
• Mumm-Ra - She's Got You High
• Chambers - Sea Mistress
• Kurt Vile - Overnite Religion
• The Coast - Nueva York
• Kanute - Not Sleeping
• The Love X Nowhere - Northern Time
• Phantogram - Mouthful of Diamonds
• Beat Radio - Memoir of Lightening
• Land of Talk - May You Never
• The Exploding Boy - London
• New Found Land - Leave It Behind
• Goyte - learnalilgivinanlovin
• Brite Lite Brite - I Just Want U 2 Myself
• Miracle Fortress - Hold Your Secrets to Your Heart
• The Pains of Being Pure at Heart - Higher than the Stars
• Bye Bye Bicycle - Haby Baby
• Evan Voytas - Getting Higher
• Ou Est Le Swimming Pool - Dance the Way I Feel
• Red Wire Black Wire - Compass
• Downtown Union - Bright Idea
• Wild Beasts - Brave Bulging Buoyant Clairvoyants
• The XX - Blood Red Moon
• The Ties and the Lies - August is for City Lovers
• Choir of Young Believers - Action Reaction
• Gossip - Music for Men
• The Swell Season - Strict Joy
• Oliver Schroer - Camino

Added to my regular rotation of Muse and Kings of Leon, these tracks ensure that I don't suffer from listening fatigue.

It took me a while to figure out how to get Fink to install ImageMagick and the RMagic gem for use with attachment_fu and I thought I would share my method. From the #rubyonrails channel on freenode, it seems that I am a Luddite; most users prefer MacPorts. As I've written before, I think there is value in understanding the ports system you are using in OS X and that there be a clear separation between system binaries and those you add yourself. Polluting the /usr directory with unsupported 3rd party code can only lead to heartache. It also helps to acknowledge the underlying software dependencies in case your production environment varies from development (which is my case). That being said, I've provided the link for those who just have to use MacPorts.

ImageMagick & Fink

Before the rmagic gem can be used, ImageMagick needs to be installed on the machine. Fink is great at being able to build from source and resolving dependencies, but in this case, it took a bit of coercion to get ImageMagick installed. At various points during dependency resolution (for ghostscript and dbus-dev), I was required to abandon FinkCommander and issue the following commands from a Terminal:

# fink scanpackages
# sudo apt-get
# sudo apt-get install ghostscript=8.61-5

# fink scanpackages
# sudo apt-get
# sudo apt-get install dbus-dev=1.2.6-1

I'm assuming that order is important in the dependency resolution process, so I included both sets of commands which needed to be run separately at different points in the installation process.

This eventually installed ImageMagick, but unfortunately, the default configuration included the dreaded --enable-hdri option. Fixing this required digging into Fink source code management internals. By default, Fink keeps ports metadata information in .info files which are arranged based on stable/unstable trees as well as by function. For ImageMagick, the relevant files were located in the /sw/fink/10.5/unstable/main/finkinfo/graphics directory. A grep against the ImageMagick files revealed that imagemagick-nox.info and imagemagic.info both contain the option. Simply removing it from these files and rebuilding the ImageMagic port resulted in an rmagic compatible installation.

# fink rebuild imagemagick

There are a number of supplementary packages that are required to build rmagic; I've included a list of the required ports:

# imagemagick
# imagemagick1-dev
# imagemagick1-shlibs
# imagemagick1-svg

In particular, be sure to have the imagemagick1-dev port installed, otherwise Magick-config will not be installed which is required for gem installation.

scripts/plugin fail

I usually try to follow the path of least resistance - In this case, it was to use the built-in plugin managment utility in Rails. Unfortunately, no matter how I spelled rmagic, the plugin could not be found in the sources packaged with 2.2.2. I even tried to find the plugin with rapt. C'est la vie.

RMagic Installation from Source

Although the preferred method of installing Rails components is by using gem, OSX's fonts break the rmagic tests that run when documentation examples are being generated. This leaves the method of last resort - installing from source. The trick is to change the allow-example-errors=no parameter to yes in the .config located in the source directory. Once this is done, run the following commands:

# sudo ruby ./setup.rb
# sudo ruby ./setup.rb install

Presto! At this point RMagic should be installed on your system. You can verify by running the following commands (as per the MacPorts installation doc):

# irb -rubygems -r RMagick
>> puts Magick::Long_version
This is RMagick 2.9.1 ($Date: 2009/01/12 23:08:35 $) Copyright (C) 2008 by Timothy P. Hunter
Built with ImageMagick 6.4.1 02/25/09 Q16 http://www.imagemagick.org
Built for ruby 1.8.6
Web page: http://rmagick.rubyforge.org
Email: rmagick@rubyforge.org

All in all, the process is not unlike a contortionist attempting to pick their nose with their pinky toe .... doable, but certainly uncomfortable. Comments welcome.

You can't really follow the the Test Driven Development methodology without writing tests as you develop. While the ROR documentation is fairly complete to get started on building an application, the organization of the documentation (as well as most reference material) seems to put testing at a lower priority in the context of the learning the Rails platform. It would be nice if the documentation illustrated TDD within the examples as well.

Fixtures

Rails provides a facility for quickly creating reproducible testing data through YAML fixture files. The key point of using a fixture as of 2.2.2 is that it is essentially a fully fledged ActiveRecord. When you run a test against a feature, one of the first things that happens is that Rails populates the database table with the fixture information. It is important that your fixture YAML file is syntactically correct - if the data specified in the file references an undefined column or violates a database constraint, Rails will fail to run the test and generate a whack tonne of arcane error messages. Don't do this unless you like to read stack traces.

Strange Boolean Behavior. If validates_presence_of is placed on a boolean attribute, it can only be assigned true values within the fixture. Attempting to assign false to the fixture attribute will break unit tests with the following error:

Attribute_name can't be blank.
 is not true.

In addition, when assigning boolean values within tests, you cannot use the false keyword. Doing so will create an invalid record. The numeric convention to assign true or false is to use 0 and 1 respectively.

Validation of Date versus DateTime Objects. Fixtures can use eRB to embed ruby code within the fixture itself. Unfortunately, when it comes to Date / DateTime attributes, the object returned by the fixture record is database dependent. In most cases, to validate date/time attributes requires using the strftime comparison. There is no way to get a Date object from a DateTime object. Seems intuitive, but Rails does not provide this facility. For simplicity, I've included the format parameters for posterity:

%a - The abbreviated weekday name (``Sun'')
%A - The  full  weekday  name (``Sunday'')
%b - The abbreviated month name (``Jan'')
%B - The  full  month  name (``January'')
%c - The preferred local date and time representation
%d - Day of the month (01..31)
%H - Hour of the day, 24-hour clock (00..23)
%I - Hour of the day, 12-hour clock (01..12)
%j - Day of the year (001..366)
%m - Month of the year (01..12)
%M - Minute of the hour (00..59)
%p - Meridian indicator (``AM''  or  ``PM'')
%S - Second of the minute (00..60)
%U - Week  number  of the current year,
        starting with the first Sunday as the first
        day of the first week (00..53)
%W - Week  number  of the current year,
        starting with the first Monday as the first
        day of the first week (00..53)
%w - Day of the week (Sunday is 0, 0..6)
%x - Preferred representation for the date alone, no time
%X - Preferred representation for the time alone, no date
%y - Year without a century (00..99)
%Y - Year with century
%Z - Time zone name
%% - Literal ``%'' character

t = Time.now
t.strftime("Printed on %m/%d/%Y")  
    #=> "Printed on 04/09/2003"
t.strftime("at %I:%M%p")            
    #=> "at 08:56AM"

Attempting to resolve the fixture issues highlights one of Rails glaring deficiencies - the lack of authoritative, comprehensive documentation. From IRC, to the blogs I researched to troubleshoot these issues, it was apparent that everyone had rather unsubstantiated opinions regarding built-in testing facilities on Rails which were largely incomplete. No application is perfect, but this is a rather obvious omission.

testhelper.rb

By default, the testhelper.rb file has the fixtures :all parameter enabled. If your scaffold YAML files are not valid, this setting will only throw a lot of unintelligible errors. To build up your test suite one model at a time, it might be useful to simply have a script with ruby commands to run tests you've already finished. For example, I have a file that I've chown to be executable which contains commands to run individual tests.

ruby unit/model1_test.rb
ruby unit/model2_test.rb

The testhelper.rb file is not all bad. In fact when used in it's primary capacity, it's quite useful. For example, instead of writing custom assertions for my unit tests, I placed a bunch of these in testhelper.rb. This allows you to follow the DRY (Don't Repeat Yourself) principle an simplify test suite creation. Combined with TextExpander, it's positively stunning how quickly you can create a fairly thorough test suite for a model. I've included some of my custom assertions so that others don't have quite the barrier to entry that I encounter:

def assert_not_valid(object, 
    msg="Object is valid when it should be invalid")
  assert(!object.valid?, msg)
end
alias :assert_invalid :assert_not_valid
  
def assert_presence_required(object, field)
  # Test that the initial object is valid
  assert_valid object
   
  # Test that it becomes invalid by removing the field
  temp = object.send field
  object.send "#{field}=", nil
  assert_invalid object
  assert !object.save, 
    "Cannot save record with invalid #{field}"
  assert object.errors.invalid?(field), "Invalid #{field}"
   
  # Make object valid again
  object.send("#{field}=", temp)
end
     
def assert_has_attribute(object, field)
  assert object.has_attribute?(field), 
     "#{object}.klass is missing #{field}"
end
	
def assert_doesnt_have_attribute(object, field)
  assert !object.has_attribute?(field), 
    "#{object}.klass is includes #{field}"
end 
	
def assert_has_readonly_attribute(class_type, field)
  attribute = class_type.readonly_attributes.find { |attr| attr == field }
  assert_not_nil attribute, 
     "#{field} read only attribute was not found."
end
	
def assert_required_length_less_than(object, field, length)
  duplicate = object.dup

  # Valid at length-1
  duplicate.send "#{field}=", "a"*(length-1)
  assert_valid duplicate

  # Valid at length
  duplicate.send "#{field}=", "a"*length
  assert_valid duplicate

  # Invalid at length+1
  duplicate.send "#{field}=", "a"*(length+1)
  assert_invalid duplicate
  assert duplicate.errors.invalid?(field), 
    "Invalid length of : #{field}"
end
	
def assert_inclusion (object, *list)
  assert list.include?(object), "#{object} not in #{list}"	
end
	
def assert_numerical(field)
  assert Integer(field) || Float(field), 
    "The field is not a number."
end
	
def assert_positive_number(field)
  assert_numerical field
  assert field > 0 , "The field is not a positive number."
end
	
def assert_negative_number(field)
  assert_numerical field
  assert field < 0 , "The field is not a negative number."
end
	
def assert_uniqueness_of(object, field)
  duplicate = object.clone
		
  assert_invalid duplicate, 
    "The #{field} attribute must be unique."
  assert duplicate.errors.invalid?(field), "Invalid #{field}"
end
	
def assert_inheritance(object_class, object)
  assert_kind_of object_class, object, 
     "#{object} is not a kind of #{object_class}."
end

Pluralization Conventions

One of the things that I needed to get used to was the use of pluralization of objects in Rails. From table names in migrations, to polymorphic has_many associations, being able to specify either single or multiple objects requires being aware of when rails expects plurals. As I mentioned in a previous article, pluralization is controlled through inflections.rb. This is something to reiterate again, unless you want to learn the hard way.

Counter Cache attributes. A counter cache attribute added to a model, is expected to be a pluralized (and possibly inflected) name. For example, to add a Comment object counter cache to another object requires the comments_count attribute to be present.

Limitiations of Single Table Inheritance

The implementation of object inheritance in Rails can only be described as extremely rudimentary. As per Fowler's description of this pattern, a single table is responsible for all base and subclass data. While this is great for subclasses that simply add attributes to a base class when they are subclassed, this does not work so well when derived subclasses have different attributes.

Lack of Class Attribute Encapsulation. Essentially, Rails implementation of STI does not allow subclasses to specify which attributes belong exclusively to themselves. An attribute that is available from one subclass is automatically available to all sibling subclasses. There is no mechanism to disable attribute accessors for certain classes, and enable them for others. It seems the only advantage of STI in rails is to provide convenient way to encapsulate methods and provide a mechanism for storing an object Class name in a table. Not exactly what I would consider Object Oriented .... While it has been suggested that attribute accessors can be overridden within the models, this seems like too much of hack that could have unintended consequences with regards to ActiveRecord behavior. The trade off is to probably code in logic in the classes to ensure that only certain attributes have valid values - the lesser of two evils.

Storage of Class Name as the Base Type in Associations. If polymorphic associations are used in conjunction with STI, the association_type by default must be the base Class name. If it is the actual class name, the association will fail. There are hacks that will allow the actual Class name to be stored by overriding the association_type attribute, but doing so is less than all encompassing. For example, having :dependent => :destroy conditions on the association will fail when this hack is implemented. This would then require manually destroying associated objects. Not really a great compromise in my opinion.

Miscellaneous

Sometimes things just don't work the way you expect them to. In most cases, it's probably just a case of the documentation not being updated with changes in the code. One particularly pernicious bug was the way in which ActiveRecord deals with obj.clone versus obj.dup.

• ActiveRecord handling of obj.dup vs obj.clone

Limitations actually a Good Thing?

• Enterprise Rails

While these limitations suggest that these areas of Rails are under developed, Martin Fowler has an interesting take on the rigidity shown by the core rails team to solving "enterprise" problems. In his article he suggests that Rails resistance to antiquated conventions which give strength to the existing system. This goes to prove just because you can do something, doesn't mean you should (such as attempting to create an Object Relational Mapper for Rails - RHibernate anyone?).

I reserve the right to withhold judgment ...

Cornerstone

I can't say enough about Subversion, but trying to keep track of changes between commits and doing diff comparisons with your working set versus the last revision is nothing short of a PITA. Thankfully, there is mature, stable graphical Subversion client for OS X - Cornerstone. It does a great job of abstracting various Subversion operations and does not suffer from extreme featuritis. Give it a try if your tired of looking up man pages to get just the right svn syntax.

Araxis Merge

While diffing files is old hat, the output is just barely human readable. Too much effort is expended by the user trying to visually grep the output. They say a picture is worth a thousand words, in the in spirit of "Ut pictura poesis" I would have to agree when using a visual diff tool. Having side by side comparisons greatly improves the ability to use diffs in a more coherent manner. Thankfully, Araxis has ported their flagship Merge tool to OS X. Like Cornerstone, the features are implemented with minimal clutter. This allows it to integrate cleanly into an XCode based work flow. With its seemless integration with Cornerstone, checking working copy diffs to a source code repository can't get any easier.

O'Reilly Safari

Do your self a favor and forget the forest of books that inevitably become obsolete and sign up for a Safari subscription. Technical books have a limited shelf life. Prevent become antiquated and get the latest documentation without the hassle of having to lug around a dead tree. It's not that I don't like physical books, but the rate at which technical documentation evolves makes it unrealistic to have a well stocked reference library without having to spend a fortune. Combined with the BookBag iPhone app, you can have your cake and eat it too.

Required database.yml parameter : database

The database.yml file requires the database : parameter in order to establish a valid connection to the database for a given user. This parameter was not present in earlier versions of the database.yml configuration file. See below for more details documentation regarding the PostgreSQL connection adapter parameters.

Database Adapters: pg versus postgres

At the time of writing this (against rails 2.2.2), there still seems to be a preference in the Rails framework for the pg driver over the postgres driver. Without the pg driver installed, the following error is displayed to the user :

/Library/Ruby/Gems/1.8/gems/activerecord-2.2.2/lib/active_record/connection_adapters/abstract/connection_specification.rb:74:in `establish_connection': Please install the postgresql adapter: `gem install activerecord-postgresql-adapter` (no such file to load -- pg) (RuntimeError)
	from /Library/Ruby/Gems/1.8/gems/activerecord-2.2.2/lib/active_record/connection_adapters/abstract/connection_specification.rb:58:in `establish_connection'
	from /Library/Ruby/Gems/1.8/gems/activerecord-2.2.2/lib/active_record/connection_adapters/abstract/connection_specification.rb:53:in `establish_connection'
	from /Library/Ruby/Gems/1.8/gems/rails-2.2.2/lib/initializer.rb:392:in `initialize_database'
	from /Library/Ruby/Gems/1.8/gems/rails-2.2.2/lib/initializer.rb:139:in `process'
	from /Library/Ruby/Gems/1.8/gems/rails-2.2.2/lib/initializer.rb:112:in `send'
	from /Library/Ruby/Gems/1.8/gems/rails-2.2.2/lib/initializer.rb:112:in `run'
	from /Users/mel/Documents/Workspace/vuespace/src/config/environment.rb:13
	from /Library/Ruby/Site/1.8/rubygems/custom_require.rb:31:in `gem_original_require'
	from /Library/Ruby/Site/1.8/rubygems/custom_require.rb:31:in `require'
	from /Library/Ruby/Gems/1.8/gems/rails-2.2.2/lib/commands/generate.rb:1
	from /Library/Ruby/Site/1.8/rubygems/custom_require.rb:31:in `gem_original_require'
	from /Library/Ruby/Site/1.8/rubygems/custom_require.rb:31:in `require'
	from ./script/generate:3
aleph:src mel$ gem install activerecord-postgresql-adapter
ERROR:  could not find gem activerecord-postgresql-adapter locally or in a repository
aleph:src mel$ sudo gem install activerecord-postgresql-adapter
Password:
ERROR:  could not find gem activerecord-postgresql-adapter locally or in a repository
aleph:src mel$ sudo gem install activerecord-postgresql-adapter
ERROR:  could not find gem activerecord-postgresql-adapter locally or in a repository
aleph:src mel$ sudo gem -r install activerecord-postgresql-adapter
ERROR:  Invalid option: -r.  See 'gem --help'.
aleph:src mel$ sudo gem install -r activerecord-postgresql-adapter
ERROR:  could not find gem activerecord-postgresql-adapter locally or in a repository

To install the correct the correct pg gem, use the following command:

# sudo env ARCHFLAGS="-arch i386" gem install pg

There seems to be a version difference between the two difference postgres adapeters : pg (0.7.9.2008.10.13) versus postgres (0.7.9.2008.01.28). Only time will tell if this will lead to framework incompatibilities.

ActiveRecord

To use the scaffolding in any meaningful manner requires a clear object model that can be used to represent system objects. The ActiveRecord::Migration class provides detailed usage information that is required to generate these classes and the associated database types. However, details such as the rails type to database type mappings are not easily found in Rails API. The following links highlight the most important features of ActiveRecord objects which will hopefully allow more informed use of this fundamental Rails object.

• ActiveRecord::Aggregations - useful when representing attributes as value objects.
• ActiveRecord::Associations - describes the use of object associations such as many-to-many, inheritance, and polymorphism.
• ActiveRecord::Base - describes the base ActiveRecord object and its associated methods and properties.
• ActiveRecord::Calculations - describes calculation methods available to ActiveRecord objects.
• ActiveRecord::Callbacks - describes the callbacks available during the lifetime of an ActiveRecord object.
• ActiveRecord::ConnectionAdapters::ConnectionHandler - describes the use of a ConnectionHandler to distribute an object hierarchy amongst different databases.
• ActiveRecord::ConnectionAdapters::ConnectionPool - describes ConnectionPools which can be used to synchronize thread access to a limited number of database connections. The Options section describes the use of the :pool and wait_timeout parameters in the database.yml configuration file.
• ActiveRecord::ConnectionAdapters::PostgreSQLAdapter - describes the database.yml configuration parameters for PostgreSQL as well as the native datatypes the adapter maps the migration datatypes to.
  • :primary_key - serial primary key
  • :string - character varying(255)
  • :text - text (upto 1GB of multi-byte characters
  • :integer - integer
  • :float - float
  • :decimal - numeric (can be specified with :precision and :scale
  • :datetime - timestamp without time zone
  • :timestamp - timestamp without time zone
  • :time - time
  • :date - date
  • :binary - bytea
  • :boolean - boolean
• ActiveRecord::Errors - describes the errors associated with ActiveRecord object operations and how to access them.
• ActiveRecord::Migration - migration specifics.
• ActiveRecord::Observer - describes Observer configuration for ActiveRecord objects which implement lifecycle callbacks.
• ActiveRecord::Reflection - ActiveRecord object reflection methods.
• ActiveRecord::Serialization - methods which support ActiveRecord object serialization.
• ActiveRecord::Transactions - describes atomic database transactions and their ActiveRecord implementation.
• ActiveRecord::Validations - describes ActiveRecord object field and condition validation methods.

Object Associations

As ever, the initial challenge when creating an application is to create an object model that reflects the system being designed without imposing unnecessary limitations. There are a number of relationships that can be modeled through Rails, but it is important to understand both the usage and limitation of these mechanisms.

• Rails only supports Single Table Inheritance - By default only Single Table inheritance is supported by Rails. Essentially, different subclasses are represented by a :type field in the database table. To avoid confusion, treat type as a Rails keyword an only use it when you want to model Inheritance.


• Polymorphism is supported through the :has_many :has_one/ :as mechanism - common functionality can be shared amongst objects by implementing an interface. This requires the implementing object to have interface_id:integer and interface_type:string columns within their database models.


• The difference between :has_one and :belongs_to is largely where the foreign key resides. - The :belongs_to implementation should have the corresponding foreign key to the referenced object.


• Many-to-many relationships can be modeled in a number of ways. Direct relationships can be modeled using has_and_belongs_to_many. If the association needs to be manipulated independently, the has_many :through relationship will do provided a join table is created to associate the two models.


• Secondary associations using :through. Both the has_one and has_many associations support secondary references through intermediate objects.

Object Hierarchies

There are built-in mechanisms with Rails to model ordered lists, trees, and hierarchies.

• :act_as_list - allows a collection of object to function as an ordered list. This requires a position column within the model.
• :act_as_tree - allows a collection to behave as a tree. Requires the parent_id column within the model.
• :act_as_nested_set - allows a collection to behave as a hierarchy. The advantage over :act_as_tree is that individual nodes can be retrieved with their dependent objects. This model requires the use of the following columns : parent_id, lft, rgt.

Validations

Data sanitation is paramount to preventing a whole host of database injection attacks. Always assume that any publicly submitted data can be used to compromise the system. To mitigate these types of attacks, ActiveRecord supports validation of conditions and fields (see above). It is highly recommended that validations be exercised in the testing framework to ensure their proper functioning.

Can you own an idea? In the era of digital content, this is a question that seems to be occluded by questions of copyright and ownership, but resides fundamentally at the heart of the issue. Although it is understood that the creator holds copyright with regards to the content created, the question of ownership is much murkier when content is duplicated for mass consumption. Who owns those duplicates? What rights are extended to the purchasers when content comes into their possession? Do they have resale rights? At what point does the original content creator relinquish their rights to the purchaser, if ever?

These questions highlight the difficulty of assigning ownership and possession to the intangible. Tangibility or the lack thereof is digital media's Achilles heel. The problem is that by its nature a tangible product or commodity is obviously limited in how many copies can be made of it. This is not true for digital goods. The simple act of transmission implies that it is being duplicated. A physical commodity does not have this characteristic. It can be resold, borrowed, but it is not duplicated in the process. In essence, tangibility is a counter agent to duplicability.

If we look at the definition of the word counterfeit:

... is an imitation that is made usually with the intent to deceptively represent its content or origins.

It is rooted in the physical nature of a commodity. Can the term "counterfeit" be applied to digital media when a copy is as perfect as the original? Does it deceptively represent its content? I think not.

There are those that will argue that media can be counterfeited. CDs, DVDs, books, can all be duplicated. This is true, but what is actually being counterfeited - the medium which delivers the content or the content itself? Ultimately, physical artifacts serve as simple distribution mechanisms. They only serve as repositories for the ideas/content they transport. This leads to a more accurate definition of media - as an amalgamation of physical distribution mechanism and content.

Most of our consumer rights focus on this the tangible asset as the focus of copyright. Once you remove the distribution mechanism out of the equation however and are left with dissociated content, what you actually own is an idea - a cultural meme without physical constraints. Can something this ephemeral ever be constrained to individual ownership?

There comes a time when version control becomes a necessity; that's when Subversion comes to the rescue. Having worked with both CVS and Subversion, I recommend avoiding the baroque intricacies of CVS for the simplicity of Subversion. This is specially true if you have a project with an evolving source tree. Follow the links above for an introduction to Subversion.

There are a few things to note however, when attempting to use Xcode 3.1 with Subversion 1.5.x. It seems that Xcode is hardwired to verify the repository version. A repository created with the 1.4 version of the svnadmin returns a version identifier of 2, whereas the 1.5 of the command creates a version 3 repository. This may have to do with the back end databases used by the repository. Without significant hacking, it seems like a lot of work with marginal benefit. For now, I'd recommend using the packaged 1.4.4 that comes with OS X 10.5.5.

One last thing: it seems that launchctl will be the default method for managing startup daemons going forward in OS X. This means that the older SystemStarter service will be deprecated in the near future. There is an article at The Wishing Line which discussed a method for automating svnserve startups using launchctl. Be sure to modify the .plist to use the correct paths for your binaries and repository. As with PostgreSQL, I created symbol links from /usr/local to the actual repository to keep a clean separation between the system defaults versus any customizations that I introduce into my computing environment through 3rd party applications.

With OS X 10.5.5, I found that the 1.4.4 version of svnserve included with the developer tools was located in the /usr/bin directory. You can verify this on your system with the following command:

# which svnserve

Take note of the path returned by this command; it is necessary for the .plist file.

One last customization to the .plist file was changing the default --daemon command argument and replacing it with the --tunnel argument to support svn+ssh. If you plan to use this feature for a network accessible Subversion server, keep in mind that you will also have to enable the Remote Login privilege to be enabled on your machine under System Preferences -> Sharing.

For the sake of completeness, here is my modified .plist file:

• Subversion .plist

	Label
	org.tigris.Subversion
	ProgramArguments
	
		/usr/bin/svnserve
		--tunnel
		--root
		/usr/local/svn
	
	RunAtLoad
	
	ServiceDescription
	Subversion Server
	StandardErrorPath
	/dev/null
	UserName
	root

As with all these articles, please feel free to comment if you find and error or wish to add something that I've overlooked.

Just a little background; I began this project when I retired my rather thirsty and ancient Pentium Pro that served as my personal firewall/gateway for my home LAN a couple of years ago. I wanted a device that would not compromise on security and flexibility (hence the requirement to support OpenBSD) but also consume a reasonable amount of power. Enter the Soekris 4801 - an AMD Geode based embedded system. Base power consumption is 5W - 12W at peek. Not a powerful machine by modern standards, but certainly more powerful than my old system and more than sufficient for my needs. This system was cutting edge in the embedded systems space when I got it, but has been superceded by the newer 5501-60. For the record, the 4801-60 has the following specifications:

• 233 Mhz i386 compatible AMD Geode CPU
• 128 Mbyte SDRAM (embedded)
• 3 SIS 10/100BaseT Ethernet ports (embeded)
• 2 RS232 Serial extensions with a single 9 pin port
• 1 32-bit Compact Flash socket
• 1 44 pin IDE 66 connector
• 1 Mini-PCI socket
• 1 3.3V PCI connector
• 1 1621 dual port SIS 10/100BaseT Ethernet card attached to the PCI connector

Soekris Engineering also manufactures an add-in mini-PCI VPN accelerator (vpn1411), but I haven't gotten around to installing one of these yet. Although, the Soekris is ideally suited for flash based firewall distros, I opted to have a full version of OpenBSD. Storage for the OS is provided through a CF adapter which houses a 6GB Hitachi Microdrive.

Like most embedded systems, there is no built-in support for external peripherals, such as keyboards, mice, and video. All communications happens through one of the two serial ports. Thankfully, the engineers at Soekris were kind enough to wire up a port, otherwise you'd be left to your own devices to rig one up for yourself. The 4801 supports comBIOS, meaning you can use a null serial cable and a communications program (such as minicom) to manage the device through its entire boot cycle. This brings us to my first tidbit; communication parameters. The 4801 supports the following :

19200 8N1
hardware and software flowcontrol off 

Be sure that your communication software is configured with these parameters - their importance will become apparent when we attempt to update the 4801 with the latest BIOS firmware. It is good practice to use the latest vendor supplied firmware to reduce the possibility of potential hardware conflicts. However, without the correct parameters, attempting to update the firmware using the built-in BIOS monitor is impossible and will result in spurious cryptic errors being thrown. There were sites which suggested that the following xmodem parameters be changed to enable communications compatibility with the 4801:

/usr/sbin/sx -vv -b -X

but from my experience, disabling hardware flow control was sufficient to ensure seemless serial communications.

The process for updating the firmware is as follows and assumes that you are already connected to the 4801 through a serial cable :

1. Download the latest firmware from Soekris.
2. Reboot the 4801. At the boot prompt, interrupt the boot process using CTRL-P. This will bring up the boot monitor.

3. The official documentation refers to the download command to initiate file transfer. There is an undocumented option to this command however which will correctly initialize the file transfer session.

   download -

   Failing to provide the additional - argument will result in NAK errors when attempting to establish the communications channel.

4. Once the file has been uploaded, issue the following command:

   flashupdate

5. Reboot.

For more detailed instructions, please see the Updating the Soekris BIOS.

As there is no direct way to supply install media directly to the 4801, updating the 4801 requires configuration for PXE booting. At this point, I'd like to point out my second major caveat regarding the upgrade process:

The Soekris 4801 does not support PXE booting on any other interface other than the first ethernet port (ETH1).

I wasted a precious amount of time learning this lesson. Heed it well. This limitation also implies that to upgrade the 4801 requires it being in a network environment where the primary network interface can be configured. If this is not the case (such as when the 4801 resides on the network boundary), you will have to move it. Kiss goodbye to an in-place upgrade.

There are two services that are required to facilitate PXE booting - tftp and dhcp. The DHCP server has to be configured to supply an optional filename to a lease request made from the 4801's primary network interface. This implies that you know the MAC address of this interface. If you do not already have it, you can get it by forcing the 4801 into booting off the network using the BIOS monitor. See below.

The following is an example of a dhcpd.conf file that supports PXE booting

# dhcpd.conf
#
# Configuration file for ISC dhcpd (see 'man dhcpd.conf')
#

## GLOBAL OPTIONS
ddns-update-style ad-hoc;
default-lease-time 1200;
max-lease-time 9600;

subnet 10.0.1.0 netmask 255.255.255.0 
	{
		range 10.0.1.101 10.0.1.200;
		option broadcast-address 10.0.1.255;
		option routers 10.0.1.1;
		option domain-name "domain.com";
	}

host soekris
	{
		hardware ethernet 00:00:24:c3:90:f8;
		fixed-address 10.0.1.100;
		filename "pxeboot";
		option host-name "soekris";
		next-server 10.0.1.10;
	}

Please note the following :

• The argument to filename is not an absolute path. It is simply the name of the pxeboot file.
• The next-server option is required.
• The ddns-update-style global option is required for newer versions of dhcpd.

Following these guidelines when configuring dhcpd will save you from needless troubleshooting.

TFTP is usually managed through inetd/xinetd. Unfortunately, this results in arp network issues. It is recommended that tftpd run in standalone mode to avoid these issues.

The last part of the tftpd configuration requires creating a directory to serve out the pxeboot and bsd.rd files. Keep in mind that by default, tftpd runs as an unprivileged user (such as nobody). Ensure that wherever you place these PXE files, they have appropriate permissions for the daemon to access. Because we are using the console to manage the boot process, this PXE installation also requires an etc directory with a boot.conf file to configure the installer to use the console. The contents of the file are as follows:

stty com0 19200
set tty com0
boot bsd.rd

The order of these configuration parameters is important. The stty must come before the set command.

Believe it or not, at this point, you are ready to install OpenBSD. To get the 4801 to boot over the network requires the following steps:

1. Reboot. Interrupt the boot process using CTRL-P to enter the BIOS monitor.

2. Issue the following boot command:

   boot f0
   

I won't belabor the install details; you can get these directly from the main OpenBSD site. There is however one last caveat in this upgrade process: when the installer has completed unpacking the file sets, you are asked whether you want to set the current serial console as the default terminal. Say Yes! If you don't, when the 4801 reboots, it will hang attempting to load the kernel. This unfortunately leads to the boot process simply hanging at the following message:

entry point at 0x200120

Took me a while to figure this out. Hopefully others will not have to suffer quite as much as I did. Thankfully, OpenBSD has finally "modernized" and supplied a cleaner upgrade path than in previous releases. Hurray!!! About fucking time.