[sword-devel] InstallMgr

Troy A. Griffitts scribe at crosswire.org
Thu May 14 09:59:24 MST 2009

To outline the supported logic for SWORD module installation as it 
currently stands:

The SWORD Project library, as of 1.6.0 currently has builtin features to 

o  Management of an existing SWORD library installation

(provided the user has proper permissions to perform the actions, etc.) 
deleting, listing, comparing to another library installation to look for 
updates/additional modules, etc.)

o  Installation of modules from another existing SWORD library 
installation via file path  (e.g., Z:\The SWORD Project\; /mnt/cdrom/)

this is useful for installing from another SWORD installation made 
available by sharing a windows drive, an organization network drive, a 
CD, DVD, USB stick, mem card, or any other way standard filesystem 
access can be obtained to another SWORD installation.

o  Installation of modules from another existing SWORD library 
installation via FTP  ( e.g., ftp://crosswire.org/pub/sword/raw )

o (NEW IN 1.6.0)  Auto-discovery of new locations for the previous.

This is done by querying the master list of known module repositories 
available here:


These are currently the officially supported methods of module 
management in The SWORD Project library.

Due to the release of the new auto-discovery features in 1.6.0, I 
believe all frontends should expose each of these features as a minimum, 
so we can have a base set of common installation means across all of our 

This gives us a unified message going forward to publisher who wish to 
make their content available.


Now, having said this,  I think it's exciting that other projects add 
their own methods catering to their user groups.

I would like to add new officially supported methods, like adding:

o  Installation of modules from another existing SWORD library 
installation via HTTP  ( e.g., 
http://crosswire.org/ftpmirror/pub/sword/raw )

A skeleton class for this method was already added in 1.6.0 so we can 
shoot to implement this in the 1.6.x branch without changing the API 


Aside from the officially supported methods of installation, there are 
caching methods we implement to assist in optimizing installation, e.g. 
if we find a mods.d.tar.gz file at the root of the 'other' SWORD library 
installation from where we're installing, we'll copy and untargz this to 
discover which modules are available, instead of copying each 
mods.d/*.conf file one at a time.

**** BUT THE IMPORTANT THING HERE in my mind, is that, while we have 
caching mechanisms in place, and while we might even add more 
(hypothetically, a zips/ folder at the root of the 'other' SWORD library 
installation where we can check for a pre-zipped module archive so we 
can avoid downloading module data files and images one at a time, and 
other methods)...

.... THE VERY IMPORTANT THING NOT TO MISS HERE....  (have I focused the 
attention of skimmers yet? :) )

	... is that these are EXACTLY THAT: CACHING/OPTIMIZATION features.  *** 
NOT *** required features to make a valid repository SWORD module 

A frontend should NOT depend on these features being available.  If they 
exist, use them-- great!  If not, please support the minimum common 
installation features outlined above.

In conclusion, we need to have, for content creators, a very low level 
of effort entrance into the hosting of SWORD modules ("do your modules 
work in your favourite SWORD application? Great, drop your working SWORD 
module installation onto a CD", "point an FTP server to your working 
SWORD module installation", (maybe future) "point an http server to your 
working SWORD module installation"  "-- and oh, by the way, here are 
some steps you can take to speed up downloads for your users, but they 
aren't required").

We need to support these most basic installation means commonly across 
our applications.

sword::InstallMgr provides support for these, so C++ frontends can make 
calls to this class to support these methods-- I believe most already do.

Unfortunately and obviously, JSword cannot depend on sword::InstallMgr 
providing this functionality for them and it will take effort to bring 
JSword-based apps up to supporting this common set of methods.  I always 
appreciate the effort the JSword teams makes to continue to walk in step 
with the C++ side of things-- often implementing their own methods which 
seem better in their eyes, but continuing their commitment to strive to 
support _at least_ (tongue in cheek) the C++ lead.


DM Smith wrote:
> On May 13, 2009, at 11:50 PM, Jonathan Morgan wrote:
>> On Thu, May 14, 2009 at 11:07 AM, Daniel Owens <dhowens at pmbx.net> wrote:
>>> You've got my vote. It seems to be an understandable confusion that 
>>> zipped
>>> modules are available but most front-ends don't support their use. 
>>> BPBible
>>> implemented the installation of modules using zipped archives, and it
>>> doesn't even have the standard module manager yet. That to me says 
>>> that this
>>> feature is easy to implement (and in my thinking long overdue). HTTP
>>> repositories are another MAJOR motivation for me too...
>> A related problem is the number of different zip formats.  Currently,
>> Crosswire has RawZip, Windows Zip (which is just intended for BibleCS,
>> IIRC) and Mac OS X (which I'm not sure is really still supported by
>> MacSword).  BPBible theoretically supports both Windows Zip and Raw
>> Zip, but I think Raw Zip is probably a better format (being at least
>> in theory application independent) and we have had a couple of bug
>> reports installing the YLT, which I haven't been able to reproduce
>> either with Win Zip or Raw Zip.  I would really prefer us to offer
>> just the one format (Raw Zip) unless there is a very good reason not
>> to, since that saves the need for users to have to make a choice.  If
>> we do have multiple formats then I think the wording needs to change
>> (currently it is "Windows users should click on the link in the
>> WINDOWS column, while Linux users should click on the link in the RAW
>> Zip column.").
> I think the windows zips are problematic except for those using The 
> SWORD Project for Windows (aka BibleCS) and sometimes even for those.
> The "windows" zip contains an Install Shield installer which stages the 
> module at c:\Program Files\CrossWire\The SWORD Program\newmods. When the 
> user starts BibleCS, a dialog comes up, stating "Found New Module", 
> giving the Description and the About from the module's conf. For most 
> modules, the dialog's text is truncated. For each module installed this 
> way the dialogs come up one after the other upon closing the prior.
> This mechanism silently fails if BibleCS is not installed to the default 
> location or if BibleCS is not installed at all. It also fails to work 
> when BibleCS is installed but not used as Bible Desktop, Xiphos, 
> Alkitab, and all others running on Windows won't look there and don't 
> have the mechanism to work that way.
> IIRC, Troy said that we had (may still have) an agreement with a 
> copyright holder to show the About info to the end user. (Correct me if 
> I am wrong.)
> Personally, I think the zips, other than the raw zips should be done 
> away with. I think Manfred said the Mac zips can go away on the download 
> page, though he won't be removing support for them in MacSword. The 
> Windows zips may have been a good idea at the time. I think that there 
> are other ways to notify the user that new modules have been installed 
> external to the program's module installer. And it would be something 
> good for all of our front-ends.
> Regarding installation of module zips, I think there are two issues here:
> 1) Install of zips that are on the user's local machine.
> 2) Install Manager download of zips via ftp or http.
> Regarding 1). I think this is a great idea. I also like the "drag it 
> onto the app to unzip" approach that David Haslam mentioned. The 
> mechanism should be part of the SWORD library. And Manfred's 
> implementation that if the zip is found in the same folder as mods.d and 
> modules, it will be automatically unzipped.
> For JSword, we have planned the ability to specify a zip by URI, which 
> could be of the file:// type. A JSword front-end could then provide a 
> local file system browser to help the user find the zip.
> Regarding 2), Troy has told me that JSword's http implementation to 
> download raw zips is not a supported SWORD mechanism and might go away 
> or change at any time. We are taking that risk as we had too many 
> problem reports regarding our FTP mechanism (e.g. WinXP blocks it, 
> doesn't work behind firewalls or proxies, ...)
> Troy has agreed that the SWORD ftp mechanism can look for the zips first 
> and failing that do the current behavior, with zips being a cached 
> representation. And that ftp might be able to be taught to generate the 
> zip on request.
> In Him,
>     DM
> _______________________________________________
> sword-devel mailing list: sword-devel at crosswire.org
> http://www.crosswire.org/mailman/listinfo/sword-devel
> Instructions to unsubscribe/change your settings at above page

More information about the sword-devel mailing list