View source for SWORD Module Source Discovery and Module Updating

= SWORD Module Remote Installation Source Repository Discovery, Module Installation, and Updating =

== Overview ==

The SWORD Project Remote Module Source Discovery, Module Installation, and Module Updating is a straightforward process which both the SWORD and JSword engine support programmatically.  Each CrossWire frontend makes these steps available to the user by calling the appropriate SWORD or JSword method for them.  There also exists a simple command line tool (installmgr) to perform these actions, and this simple tool provides to SWORD frontend developers a great example of how to perform each of these steps from within their application.  The steps can generally be list as these; more details about each can be found below:

# Warn user about the risks.
# Query CrossWire to obtain the list of known publishers of SWORD materials.
# Query each publisher for a list of available resources.
==== Installation ====
# Present available resources to user.
# Display the detail for a selected module.
# Install the module.
# Check to see if the module is enciphered and obtain that code from the user.
==== Update ====
# Refresh resource list obtained in step #2.
# Iterate all installed modules and see if the installed module has a version number less than the version number in the refreshed resource list.
# Present to the user the history list between the user's installed version and the available updated version, to inform the user what has changed and ask if an update is desired.
# Uninstall the module.
# Install the updated module.

Each of these steps has a simple method available to the programmer from the SWORD engine.  

== 0. Warn user about the risks. ==

CrossWire has a policy to always warn users before enabling Remote Module Installation.  Many of our users live in persecuted countries and using CrossWire's systematic method for installing modules from remote sources poses a risk of detection for these users.  This is the warning we typically present during an application run the first time any Remote Module Installation action is requested:

 <nowiki>
                -=+* WARNING *+=- -=+* WARNING *+=-


Although Install Manager provides a convenient way for installing
and upgrading SWORD components, it also uses a systematic method
for accessing sites which gives packet sniffers a target to lock
into for singling out users. 


IF YOU LIVE IN A PERSECUTED COUNTRY AND DO NOT WISH TO RISK DETECTION,
YOU SHOULD *NOT* USE INSTALL MANAGER'S REMOTE SOURCE FEATURES.


Also, Remote Sources other than CrossWire may contain less than
quality modules, modules with unorthodox content, or even modules
which are not legitimately distributable.  Many repositories
contain wonderfully useful content.  These repositories simply
are not reviewed or maintained by CrossWire and CrossWire
cannot be held responsible for their content. CAVEAT EMPTOR.


If you understand this and are willing to enable remote source features
then type yes at the prompt

enable? [no] 

</nowiki>

Also, because user from these countries often do not speak English, we ask the user to type a response to enable the feature.


== 1. Query CrossWire to obtain the list of known publishers of SWORD materials. ==

To discover the list of available module remote source repositories from publishers using the installmgr command line tool:

installmgr -sc

==== Details ====
The registry of all known and endorsed module remote source installation repositories is located at this URL and is pull by SWORD and JSword automatically to satisfy this step (e.g., by the command: installmgr -sc)

[https://crosswire.org/ftpmirror/pub/sword/masterRepoList.conf https://crosswire.org/ftpmirror/pub/sword/masterRepoList.conf]


== 2. Query each publisher for a list of available resources. ==

To get a list of available publishers of remote SWORD module sources

installmgr -s

To refresh one of these, e.g., the "CrossWire" source:

installmgr -r "CrossWire"

==== Details ====

A module remote installation source repository is simply a set of SWORD resources installed in the same way as they would be installed for use by a SWORD frontend, but also made available online via FTP or HTTP.  There may be optional additional files included which can speed up the use of large repositories, and some additional files currently needed to support JSword (until their install tools are improved to match our main SWORD engine), but essentially, any installed module set can be used as a module installation source for use by other SWORD users to choose and install modules.



== 3. Present available resources to user. ==

To display resources available from a publisher, e.g., from the "CrossWire" source:

installmgr -rl "CrossWire"

== 4. Display the detail for a selected module. ==

To display the details for a module, e.g., the KJV available from CrossWire:

installmgr -rdesc "CrossWire" KJV
 
== 5. Install the module. ==

To install, e.g., the KJV from CrossWire remote source repository:

installmgr -ri "CrossWire" KJV

== 6. Check to see if the module is enciphered and obtain that code from the user. ==

To check if the NA28 module from the "Deutsche Bibelgesellschaft" source repository needs an unlock key:

installmgr -rdesc "Deutsche Bibelgesellschaft" NA28|grep "^\[CipherKey"

==== Details ====

A modules' .conf file will include a CipherKey entry to designate that the module is enciphered and needs a key to use.  Once the user provides the key, it should be entered as the value for the CipherKey entry, e.g.,

[ModuleName]
CipherKey=xyzzy

Typically these and other user-supplied settings for a module should be kept in their own .conf file and merged into the SWORD config, e.g.,

SWMgr library;
library.config->augment(SWConfig("~/.sword/userPreferences.conf"));

Where ~/.sword/userPreferences.conf would contain sections for each module along with the properties to augment:

[ModuleName]
CipherKey=xyzzy

This is valuable when updating a module, so as not to lose the any user-supplied preferences when uninstalling and then re-installing the module during the update.

== 7. Refresh resource list obtained in step #2. ==

== 8. Iterate all installed modules and see if the installed module has a version number less than the version number in the refreshed resource list. ==

To check for updates in, e.g., the CrossWire repository:

installmgr -rd "CrossWire"|grep "^+"

==== Details ====

Each module's .conf file contains a Version property which tells the module's current version.  Installmgr's -rd flag will only show new (lines beginning with a '*') and updated (lines beginning with a '+') modules.


== 9. Present to the user the history list between the user's installed version and the available updated version, to inform the user what has changed and ask if an update is desired. ==

installmgr -rdesc CrossWire Nave|grep "^\[History"

==== Details ====

A module's .conf file will include History_version properties which describe what was updated for that version of the module.
It is desirable to only display to the user the History_version lines which are between the user's currently installed module version and the latest version which they are queried if they would like to update.


== 10. Uninstall the module. ==

To uninstall the KJV module:

installmgr -u KJV

== 11. Install the updated module. ==

installmgr -ri "CrossWire" KJV