Difference between revisions of "Installing and Configuring LDDTool"

From The SBN Wiki
Jump to navigation Jump to search
m
Line 198: Line 198:
  
 
I haven't actually tested whether or not you can rename the <code>LDDTool</code> directory itself.  If you do try that and have anything to report, let me know...
 
I haven't actually tested whether or not you can rename the <code>LDDTool</code> directory itself.  If you do try that and have anything to report, let me know...
 
== Update User Path ==
 
==== On Linux-based Systems ====
 
==== On Windows Systems ====
 
  
  

Revision as of 15:34, 24 March 2015

LDDTool is the low-level tool that takes an input XML document and converts it into the various types of structured files used to define, document, and use a local data dictionary in PDS4 labels.

Introduction

A local data dictionary is a set of schema files that define a namespace that is under the control of someone other than the PDS4 managers. It includes the PDS discipline dictionaries for things like display orientation and geometry, as well as node- and mission-specific dictionaries. There are web-based and GUI-based tools in development at various places to help users who prefer to do dictionary development in an web/GUI environment - ask your friendly, neighborhood PDS node consultant what's currently available if that's what you're looking for. These pages are for the roll-your-own crowd that either prefers or has no choice but to work at the command line and see how the sausage is made.

Caveat Usor

Be advised: There is a fair amount of hands-on setup work required to get the LDDTool working in your local environment the way you want it to. And because this is beta-release software, you may well have to repeat this process in new, interesting, and undocumented ways with each new release. We'll try to keep this page updated to reflect the latest version of the tool. Feel free to add additional information about LDDTool versions or OS versions not specifically mentioned here. Contact Anne Raugh at the Small Bodies Node for permission to edit this Wiki if you don't have it already. Thanks!


Goal

Our goal in this set of pages is to start with the LDDTool installation package and end up with the tool installed for general use on the target system. "General use" in this case means you can invoke the tool any directory where you happen to be working with a command line that looks something like this:

    % lddtool -lp <input_file>


Part List

To run the LDDTool locally, you'll need the following:

  • The LDDTool ZIP package. Because this software is not officially released, you'll need to get this from your PDS contact. If you don't have a PDS contact, try contacting Anne Raugh at the Small Bodies Node.
  • Java 1.6 or later. Type "java -version" at your command line to see what version of Java, if any, you have available. If you don't have Java installed, or want to work with a later version, you'll usually need administrator privileges on your computer to download and install a newer version from the Oracle web site https://java.com/download. Java 1.7 and later includes a handy feature that will help with configuration later on, so if you're still running a (relatively) ancient version, you now have one more reason to upgrade.
  • A text editor that can handle simple text files for batch processing without filling them up with stupid control characters. On linux-based systems, things like vi, pico, or gedit will work; from the Windows DOS command line, you can use the edit command on older systems (pre-Windows7), or Notepad (which can be invoked from the command line) on newer ones.
  • An XML editor, while optional, will make editing the output schema files easier, and you'll probably want one for creating the input file anyway. A schema-aware editor like Eclipse (open source) or oXygen (commercial) can be very handy for one-off file creation and editing. For the minor fix-up editing needed in the LDDTool output schemas, though, you can use the same simple text editor you used to edit the batch file or command wrapper.


General Procedure

Here's the general procedure for setting up the tool:

  1. Unzip the LDDTool package.
  2. Move the directories you actually need to run the tool to a permanent location.
  3. Edit the wrapper script for the local environment.
  4. Install the wrapper script.
  5. Test the installation with the supplied sample files.
  6. Rejoice in the knowledge of a job well done.

Procedure

Unzip the LDDTool Package

Use any standard ZIP tool (unzip on linux-based systems; the Extract All option in Windows Explorer) to extract the files from the ZIP package. You will likely end up with a directory with the name LDDTool. On a Windows system, by default this directory will be underneath a directory with the same name as the ZIP package, less the ".zip" extension. You can unpack it anywhere - we'll move the stuff we need to a new home once we've picked one out. If you haven't inspected previous LDDTool delivery packages, you should probably take a few minutes to familiarize yourself with the contents.

What's in the Package

Executable

The executable elements of the package include:

bin/
You'll actually only need one of the files from this directory, but you'll have to carry the directory along nonetheless. We'll be modifying one of these scripts to work on your local system, and then installing just that modified file into an LDDTool-specific bin/ directory.
Data/
At least one of these files is referenced directly by the LDDTool java code, so it needs to be present.
lib/
This directory contains only the DMDocument.jar jar file, which contains the actual Java code.

Documentation

The doc subdirectory contains documentation files, mainly in the form of PDF files.

  • The file with "Installation" in the name provides some general configuration information for LDDTool.
  • The file with "Operations" in the title provides an overview of how to run the tool with some example command lines.
  • The file with just "IngestLDD" followed by a string of numbers and underscores that looks like it might be a version number is a rough guide to filling out the Ingest_LDD document that is the input to the LDDTool. There are some very useful tables in it you might want to keep handy when it comes time to create your input file.

Examples

This directory contains sets of input/output files produced by LDDTool. They are undocumented, but at least if you run the usual lddtool -lp command on the IngestLDDTool_*.xml you should get output very similar to the file set here. We'll use one of these for testing the installation. Apart from that, they may be useful examples for how to code some of the more specific, more complex behaviour found in the more intricate discipline dictionaries.

Peanuts

Like packing peanuts, these files are included in the package but are not, as far as I have found, particularly useful once the package is opened:

  • AAREADME.txt: This looks like output from a linux man command, and could be a handy one-page reference for command line format and options if typing "lddtool" becomes onerous.
  • runapp.bat: A Windows-style batch file that demonstrates how to invoke an executable in the bin directory for the sample file IngestLDDTool.xml. It will not run out of the box - you must configure the lddtool.bat file it invokes first, and then make this file executable. It is not generally configurable as is because input and output file names are hard-coded.
  • Schemas/: This directory contains a couple of superseded PDS4 schema files for the core PDS4 namespace. I'm not sure why it's here; the tool seems to run fine if this directory is expunged.

Install the Executable and Support Directories

Unless you're seriously hardcore, you will be running LDDTool by invoking a wrapper script (or batch file). This script sets up some environment variables and then calls Java with the appropriate options and arguments to run on the DMDocument.jar file with the options and arguments passed to the wrapper script.

Note: The classes in the DMDocument.jar file read all the environment variables set by the wrapper script/batch file, and also contain hard-coded references to the Data subdirectory in the installation tree. So wherever you install LDDTool, you're going to need to preserve the delivery tree structure for the bin/, lib/, and Data/ subdirectories - and the wrapper script must be physically located in that bin/ directory.

Choosing an Installation Location

On linux-based multi-user systems, you can install LDDTool for general use by all users either by installing into one of the standard locations (/usr/share, for example), or in shared disk space. If the latter, users wanting to execute LDDTool will likely have to add the appropriate location to their $PATH setting. Alternately, you can install it into your own ~/bin/ directory for personal use. Note that if you haven't created or used a personal ~/bin/ directory before, you may have to add it to your $PATH to use it.


On Windows systems, you can install it into the "Program Files\" directory for general use (this may require admin privileges), or in your own directory space for personal use. You will likely have to modify %PATH% setting information to make the executable visible to users without requiring a complete path specification to run the batch file. More on that later.

What to Copy/Move

Create a directory in your chosen installation location to hold the LDDTool tree. You can name this LDDTool, or include a version number, or rename it anything convenient. The name of this directory is not significant to the code.


Under this directory, copy over the entire contents of the lib/ and Data/ directories from the installation package. You will also need to create a bin/ directory, into which you should copy either the lddtool linux script or the lddtool.bat Windows batch file, as appropriate for your environment. For linux users, you will likely also have to make the lddtool script executable.


At this point you may also want to copy over the contents of the doc/ directory, for easy reference. I also copy the AAREADME.TXT file from the root of the install package into this directory, just in case I want to find it again later.

Edit the Wrapper Script/Batch File

The lddtool script (linux) or lddtool.bat file (Windows) is used to run the tool. This file will need to be edited to conform to the installation environment. Any simple text editor can do the job.

The only line you should have to change is the one that contains the definition of the JAVA_HOME environment variable. Finding the right value for and then setting this variable can be difficult, especially for folks who are not Java programmers. Since you'll need to do this a lot for other PDS-provided PDS4 tools, we've put the info into a separate page for better referencing:

Install the Wrapper Script/Batch File

The first step for installing the wrapper is a simple matter of copying to the installation bin/ directory (if it isn't there already). On linux-based systems, you will also likely have to change the script permissions to make it executable by those allowed to execute it.

You can, of course, always execute the script/batch file by using its full, absolute path on the command line. For ease of use, though, most people prefer to have their executables available in their path. Unfortunately, because of the hard-coded references in the LDDTool code, you can't just copy the script or batch file into a directory already in your path. But you can add the LDDTool bin/ directory to your path, or in linux-based systems you have the option of defining an alias to the physical location in an existing path directory.

Setting Windows %PATH%

If you only want to add the lddtool.bat location to your path temporarily, say for testing, you can enter something like this at the command prompt:

    C:>set PATH=%PATH%;C:\Users\LDDTool\bin

where C:\Users\LDDTool\bin should be replaced with whatever the full path is to your LDDTool bin/ directory. This appends the path you provide to the current value of the %PATH% variable.


If you'd like to add the LDDTool path to your default PATH once and for all, you can follow the instructions on this page for your particular flavor of Windows:


Setting Linux-based $PATH

The method used for adding a directory to your current PATH varies based on the shell you use. The Bourne shell requires an assignment followed by an export command to make the new path visible to programs you run:

   % PATH=$PATH:/usr/share/LDDTool/bin
   % export PATH

where /usr/share/LDDTool/bin is replaced with the full path to the LDDTool installation tree bin/ directory.

For C-shell and related shells, use a setenv command:

   % setenv PATH $PATH":/usr/share/LDDTool/bin"

or the set command:

  % set PATH=($PATH /usr/share/LDDTool/bin)

For either type of shell, you can do this at the command line before beginning your work with LDDTool, or you can add the lines to your shell resource file so it's already there every time you log on.

If you don't know what any of this means, it is time to seek out your friendly, neighborhood Linux programmer and ask, or try Googling "Setting environment variables" for your particular operating system.

Linux Alternative to Extending $PATH: Aliases

So far, at least, as long as the lddtool script is physically located in the LDDTool installation tree as described previously, you can create a link to the script from some more convenient place so that you don't have to modify your $PATH just to run lddtool. You'll need to have write permission to some directory already in your path. You can do this in your own ~/bin/ directory, for example (assuming it's already in your path).

To do this, simply create a link to the lddtool script from the directory already in your path. Say, for example, that the LDDTool tree is in your home directory and is called LDDTool:

   % ls ~/LDDTool
   bin            Data           doc            lib

Create a link to the ~/LDDTool/bin/lddtool file in the ~/bin/ directory thus:

   % cd ~/bin
   % ln ~/LDDtool/bin/lddtool


If you want to start using lddtool immediately in the same shell window, you will have to source your shell resource file to force it to re-read your path contents. Apart from that rare circumstance, lddtool should be in your path every time you start a new shell from now on.


A similar method can be employed (by users with sufficient privileges) to create a link in an existing system bin/ directory for general use.


Mac Users Note

Mac users should be aware of a minor but possibly annoying detail when defining aliases. The Mac flavor of Linux, while allowing mixed-case file names, does not consider case significant when comparing file names. So if, for example, you decided to install LDDTool into ~/bin/LDDTool, and then tried to create a link called "lddtool" to ~/bin/LDDtool/bin/lddtool in the same directory, you'd get an error message telling you a file by that name already exists.


To get around this you can, of course, move the LDDTool tree; or you can give the link a different name using the second argument to the "ln" command:

   % ln ~/bin/LDDTool/bin/lddtool makeldd

Now to invoke the lddtool script, you would use the makeldd alias, e.g.:

   % makeldd -lp IngestLDDtool.xml

I haven't actually tested whether or not you can rename the LDDTool directory itself. If you do try that and have anything to report, let me know...


Test the Installation

Running LDDTool on the Sample File

Expected Results

Rejoice