Bocca bin design

The problem is to how to install the tools, and once installed, how they determine context information.

The prior competing approaches are:

• .svn or CVS like-- context is entirely in the directory and a single install of the bocca utilities can cover the whole machine.
• rails-like where each project gets its own installed copy of the tools.

The CVS-like approach suffers from versioning: what if the system maintainer installs a new version of bocca and we've changed something internally? This fails the use-case where one project migrates and another doesn't. Of course the supercomputing centers get around this with 'modules' or equivalent, but it's a real hassle, and the rest of us get stuck trying to figure out what PATH to set and having to change it constantly.

The completely-rails-like approach avoids version issues, but suffers from a potential proliferation of PATH (mis)settings or variant names of executables and can subtly fail the use-case where the user wants to copy-modify an entire project tree.


A resolution that handles both use-cases cleanly is:

• First we clean up everything in bocca data-files so that path relative-to-root is used. Without this, we fail the use-case of copy-and-modify to edit a project. Then we take the following steps to ensure we find the right root dir every time.
• Create a script (sh) named bocca that is small and very unlikely to change even if all the implementation details of the utility scripts and RC/config files do change. This script is installed as /usr/local/bin/bocca, or anywhere else the user wants. It's only job is to check context and dispatch to the boccalib that matches the context.
• When creating a bocca project (bocca init $PROJNAME), that project (optionally) gets a directory at its top-level named boccalib-$PROJNAME which contains the entire set of utilities installed in the usual pattern (bin/, share/, include/, lib, etc/ underneath).
• At the top of a bocca project is the RC (config?) file specific to that project (what components, ports, etc).
• In each directory where bocca scribbles on any kind of file within a project, a .bocca/ subdir is created. In it is a file .bocca/Dir-$PROJNAME containing the relative path from the dir containing the RC file to the local dir. This is like CVS/Repository, but avoids the problems that you get if you copy the CVS/Entries file from one repository over another accidentally. Projects can arbitrarily cohabit the filesystem.
• (There was earlier proposed a .bocca/Root-PROJ file which proved to be both painful and unnecessary.)

The proposed approach captures the context, allows the user run without PATH juggling, and allows checking of critical and likely user misbehaviors:

• copying one component to another directory to modify without going through 'bocca clone component'.
• copying an entire project to modify (which isn't really misbehavior at all).
• installing a conflicting version of bocca.
• running different bocca projects in the same directory tree (provided our RC filename at the top includes $PROJNAME for disambiguation, and provided we have an option for specifying which PROJNAME any command issued applies to if it is ambiguous).
• copying a bocca component on top of another bocca component in the directory tree.

Further this allows the users of bocca to keep their RC file under version control and rebootstrap the rest of the boccalib whereever they move their source code-- neither we nor they will want them keeping bocca utility scripts under their version control in most cases.


I like this overall, and especially avoiding the PATH madness. I need to think more about the details, but I can't see anything problematic.


The case where two projects are rooted in the same directory means each cannot have its own independent boccalib unless we rename boccalib to boccalib-$PROJNAME. This is precisely the case if we truly want to support overlay behavior sanely. This makes the hard things possible without making the simple things annoying.