     [file version.texi not included]

UDUNITS-2
*********

This manual describes the UDUNITS-2 package, which contains a C library for units of physical quantities and a unit-definition and value-conversion utility.

     [file LICENSE not included]

Introduction
************

The UDUNITS-2 package provides support for units of physical quantities. Its three main components are: 1) a C library (udunits2lib) for units of physical quantities; 2) a utility (udunits2prog); for obtaining the definition of a unit and for converting numeric values between compatible units; and 3) an extensive database of units.

How This Package Differs from the Original UDUNITS Package
**********************************************************

The UDUNIT-2 package differs from the original UDUNITS package in the following ways:

  * Support for non-ASCII characters: The original UDUNITS package only supports the ASCII character set.  The UDUNITS-2 package supports the following character sets: ASCII, ISO 8859-1 (Latin-1), and the UTF-8 encoding of ISO 10646 (Unicode).  This means that unit string specifications like "µ°F·Ω⁻¹" are now supported (your viewer must support UTF-8 to display this string correctly).

  * Support for logarithmic units:  The unit string specification "0.1 lg(re 1 mW)" specifies a deciBel unit with a one milliwatt reference level. Such units are fully integrated into the package and all meaningful operations and conversions are supported.

  * Persistent value converters: It is now possible to obtain a converter data-object, which can be used to convert numeric values in one unit to numeric values in another, compatible unit.  The values can be float, double, or one-dimensional arrays of floats or doubles.

  * Improved API:  Due to the above changes, it was not possible to keep the application programming interface (API) of the original UDUNITS package.  The new interface, however, is easily understood and easy to use.  To support backward comptibility, the package does contain a version 1 C API, which uses the version 2 library.

  * XML unit database:  The unit database is encoded using human-readable XML rather than a custom format.  The XML parser included in the package supports an <import> element to allow easy and convenient customization.

  * No Fortran or Perl API:  Interfaces for these languages have not yet been created.  Contact support-udunits@unidata.ucar.edu if you are interested in helping to create these interfaces.

One thing that has not changed is that almost all unit string specifications understood by the original UDUNITS package are also understood by the new UDUNITS-2 package.  The one exception is the symbol g, which in the original package was associated with standard free fall (a unit of accelleration) but which is associated with gram in the new package.

Obtaining this Package
**********************

Get this package from its download-page at http://www.unidata.ucar.edu/downloads/udunits/ and unpack it in an appropriate place, e.g.,

     cd /usr/local/src
     gunzip -c udunits-VERSION.tar.gz | pax -r

Installing this Package
***********************

Short Installation Instructions
===============================

Not all development enviroments can build and install this package. See the long instructions in the next section for details.

The following assumes that you are familiar with autoconf-based package-installation. If you're not, then follow the long instructions in the next section.

     ./configure [--prefix=ROOT] [--disable-shared] [CC=PATH]
     make
     make check    # optional; requires CUNIT installation
     make install
     make install-info install-html install-pdf
     make clean

By default, the installation root is /usr/local.

If you encounter problems, then follow the instructions in the next section.

Long Installation Instructions
==============================

 1. Go to the top-level source-directory of this package, e.g.,

          cd udunits-VERSION

 2. Because some make utilities cannot build this package correctly, locate the operating system that is closest to yours in the following table and determine the MAKE utility that you will use.

               [file make.texi not included]

 3. If necessary, clean-up from a previous installation attempt by making the distclean target using the MAKE utility from step 2:

          MAKE distclean

 4. Because some compilers cannot build this package correctly, locate the operating system closest to yours in the following table and determine the compiler that you will use and any required option for the configure script.

               [file success.texi not included]

     The option --disable-shared causes the build process to create a static library only: a sharable library is not created. This option is necessary if the libtool utility that's included in this package can't build a sharable library using the given compiler.

     The following table lists the build environments that do not work --- so don't use them:

               [file failure.texi not included]

 5. Execute the configure script. Specify the installation prefix, the compiler from the previous step, and any required option. For example, if you are on an HP-UX system and want to use the /bin/c89 compiler and install under /opt, then the following command is appropriate:

          ./configure --prefix=/opt --disable-shared CC=/bin/c89

     If the installation prefix is not specified, then the default is to install under /usr/local.

     If the compiler isn't specified, then the default is to use gcc.

 6. Build this package by making the default target using the MAKE utility from step 2:

          MAKE

 7. If you wish to verify that this package works correctly, then make the check target using the MAKE utility from step 2:

          MAKE check

     This step is only effective if the configure script found an installed CUNIT unit-testing package.  If that package wasn't found, then the above command will quickly exit without testing this package.

 8. Install the library (udunits2lib), utility (udunits2prog), header-files, and units-database by making the install target using the MAKE utility from step 2:

          MAKE install

 9. If desired, install the documentation by making one or more of the following targets using the MAKE utility from step 2:

          MAKE install-info install-html install-pdf

 10. Clean up by making the clean target using the MAKE utility from step 2:

          MAKE clean

What Gets Installed
===================

By default, the following files are created or installed under the installation directory:

     bin/:
     udunits2                # Unit utility (udunits2prog)

     include/:
     converter.h             # API for value converters
     udunits2.h              # API for units

     lib/:
     libudunits2.a           # Static unit library (udunits2lib)
     libudunits2.la          # libtool(1) reference for unit library (udunits2lib)
     libudunits2.so          # Link to shared library (udunits2lib)
     libudunits2.so.0        # Link to shared library (udunits2lib)
     libudunits2.so.0.0.0    # Shared library (udunits2lib)

     share/:
     doc                     # Directory. Created if it doesn't exist
     info                    # Directory. Created if it doesn't exist
     udunits                 # Directory. Created if it doesn't exist

     share/doc:
     udunits                 # Directory. Created if it doesn't exist

     share/doc/udunits:
     udunits2.html           # HTML documentation on this package
     udunits2lib.html        # HTML documentation on the unit library (udunits2lib)
     udunits2lib.pdf         # PDF documentation on the unit library (udunits2lib)
     udunits2.pdf            # PDF documentation on this package
     udunits2prog.html       # HTML documentation on the unit utility (udunits2prog)
     udunits2prog.pdf        # PDF documentation on the unit utility (udunits2prog)

     share/info:
     dir                     # Top-level "info" file.  Created if it doesn't exist
     udunits2.info           # INFO documentation on this package
     udunits2lib.info        # INFO documentation on the unit library (udunits2lib)
     udunits2prog.info       # INFO documentation on the unit utility (udunits2prog)

     share/udunits:
     udunits2.xml            # Default unit database
     udunits2-accepted.xml   # Units accepted for use with the SI
     udunits2-base.xml       # SI base units
     udunits2-common.xml     # Common, non-SI units
     udunits2-derived.xml    # Derived units of the SI
     udunits2-prefixes.xml   # SI unit prefixes

Support for this Package
************************

The home-page for this package can be found at http://www.unidata.ucar.edu/software/udunits/.

Bug reports should be sent to support-udunits@unidata.ucar.edu.