udunits2.texi

\input texinfo  @c -*-texinfo-*-
@c %**start of header
@setfilename udunits2.info

@include version.texi

@settitle UDUNITS @value{VERSION} Manual
@c %**end of header
@dircategory Science
@direntry
* udunits-2: (udunits2).  The Unidata package for units of physical quantities.
@end direntry
@copying
@include COPYRIGHT
@end copying

@titlepage
@title The UDUNITS-2 Package
@author Steven R. Emmerson

@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top, Introduction, (dir), (dir)
@top 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.

@insertcopying
@end ifnottex

@menu
* Introduction::        Introduction
* Differences::		    How this package differs from the UDUNITS-1 package
* Installation::        Installing this package
* Library::             The unit library
* Utility::             The unit utility
* Database::            The unit database
* Support::             Support for this package
* Complete Index::      Complete index
@end menu

@node Introduction, Differences, Top, Top
@chapter Introduction
@cindex Introduction

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

@node Differences, Installation, Introduction, Top
@chapter How This Package Differs from the Original @code{UDUNITS} Package

The @code{UDUNIT-2} package differs from the @code{UDUNITS-1}
package in the following ways:
@itemize @bullet

@item @strong{Support for non-ASCII characters:}  
The @code{UDUNITS-1}
package only supports the ASCII character set.  The @code{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 "@code{µ°F·Ω⁻¹}" are now supported (your
viewer must support UTF-8 to display this string correctly).

@item @strong{Support for logarithmic units:}  The unit string
specification "@code{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.

@item @strong{Persistent value converters:}
It is now possible to obtain a @emph{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 @code{float}, @code{double}, or
one-dimensional arrays of @code{float}s or @code{double}s.

@item @strong{Improved API:}  Due to the above changes, it was not
possible to keep the application programming interface (API) of the
@code{UDUNITS-1} 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.

@item @strong{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 @emph{<import>} element to
allow easy and convenient customization.

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

@end itemize

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

@node Installation, Library, Differences, Top
@chapter Installing this Package
@cindex installation

@menu
* Binary::              Installing from a binary distribution
* Source::              Installing from a source distribution
@end menu

@node Binary, Source, , Installation
@section Installing from a Binary Distribution
@cindex Installation, binary

@subsection 64-bit CentOS 6.4
If your operating system is compatible with 64-bit CentOS 6.4 (e.g., your system
is 64-bit CentOS, Fedora, or RedHat), then create the file
@code{/etc/yum.repos.d/unidata.repo} with the following contents:

@example
[unidata]
name=Unidata Repository
baseurl=http://www.unidata.ucar.edu/repos/yum/CentOS/6/$basearch
enabled=1
@end example

You should then be able to install this package in the usual manner.
For example,

@example
su -
yum install udunits
@end example

@subsection 32-bit Ubuntu 12
If your operating system is compatible with 32-bit Ubuntu 12 (precious pangolin)
(e.g., your system is 32-bit Debian or Ubuntu), then add the following line to
the file @code{/etc/apt/sources.list} or
@code{/etc/apt/sources.list.d/unidata.list}:

@example
deb http://www.unidata.ucar.edu/repos/apt i386/
@end example

You should then be able to install this package in the usual manner.
For example,

@example
su -
apt-get update
apt-get install udunits
@end example

@node Source, , Binary, Installation
@section Installing from a Source Distribution
@cindex Installation, source

@menu
* Prerequisites::       Prerequisites for this package
* Obtain::              Obtaining this package
* Unix::                Installing on Unix-like environments
* Windows::             Installing on Windows environments
@end menu

@node Prerequisites, Obtain, , Source
@subsection Prerequisites for This Package
@cindex prerequisites for this package

The Expat library and header-files must be installed. Look for the library 
"libexpat" and the header-file "expat.h".

If this package is to be tested (which is optional), then the CUnit library
and header-files must be installed. Look for the library "libcunit" and the
header-files "CUnit/CUnit.h" and "CUnit/Basic.h".

If this package is to be built on a Windows system, then the CMake and MinGW
packages must be installed. Look for the utility "cmake" and the
directory/folder "MinGW".

@node Obtain, Unix, Prerequisites, Source
@subsection Obtaining this Package
@cindex obtaining this package

Get the source for this package from its download-page at
@uref{ftp://ftp.unidata.ucar.edu/pub/udunits/}
and unpack it in an appropriate place. For example,

@example
su -
cd /usr/local/src
wget -O - ftp://ftp.unidata.ucar.edu/pub/udunits/udunits-@value{VERSION}-Source.tar.gz |
gunzip -c | pax -r
@end example

@node Unix, Windows, Obtain, Source
@subsection Unix Installation Instructions

@menu
* Autoconf::    Autoconf-based installation
* CMake::       CMake-based installation
@end menu

@node Autoconf, CMake, , Unix
@subsubsection Autoconf-based Installation

Short instructions:

@example
./configure [--prefix=@var{root}] [--disable-shared] [CC=@var{path}]
make
make check                      # optional; requires CUNIT installation
make install                    # also installs INFO documentation
make install-html install-pdf   # optional
make clean
@end example

By default, the installation root is @code{/usr/local}.

Long instructions:

@enumerate
@item
Go to the top-level source-directory of this package, e.g.,
@example
cd udunits-@value{VERSION}
@end example

@item
If necessary, clean-up from a previous installation attempt by making
the @code{distclean} target using the @var{make} utility from step 2:
@example
@var{make} distclean
@end example

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

@item
Execute the @code{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 @code{/bin/c89} compiler and install under @code{/opt},
then the following command is appropriate:

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

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

If the compiler isn't specified, then the default is to use
@code{gcc}.

@item
Build this package by making the default target using the @var{make} utility
from step 2:
@example
@var{make}
@end example

@item
If you wish to verify that this package works correctly,
then make the @code{check} target using the
@var{make} utility from step 2:
@example
@var{make} check
@end example
This step is only effective if the @code{configure} script found an
installed @code{CUNIT} unit-testing package.  If that package wasn't
found, then the above command will quickly exit without testing this
package.

@item
Install the @ref{Top, , library, udunits2lib}, 
@ref{Top, , utility, udunits2prog}, header-files, units-database, and
INFO documentation files by making 
the @code{install} target using the @var{make} utility from
step 2:
@example
@var{make} install
@end example

@item
If desired, install the HTML and PDF documentation files by making 
one or more of the following targets 
using the @var{make} utility from step 2:
@example
@var{make} install-html install-pdf
@end example

@item
Clean up by making the @code{clean} target using the @var{make} utility
from step 2:
@example
@var{make} clean
@end example
@end enumerate

@node CMake, , Autoconf, Unix
@subsubsection CMake-based Installation

@example
cmake
make all [test] install [install_test]
@end example

where the arguments in square brackets are optional.

@node Windows, , Unix, Source
@subsection Windows Installation Instructions

Currently, only a 32-bit @uref{http://www.mingw.org,MinGW}-based installation is
supported:

@example
cmake -G "MinGW Makefiles"
cmake --build . [-DCMAKE_INSTALL_PREFIX=@emph{dir}] -- all [test] install [install_test]
@end example

where arguments in square brackets are optional.

The default installation-prefix is 
"@code{C:\Program Files (x86)\udunits-2.}@var{minor}.@var{bug}", where 
@var{minor} and @var{bug} are the minor version and bug-fix level,
respectively.

@node Library, Utility, Installation, Top
@chapter Unit Library
@cindex Library,  unit
@xref{UDUNITS Library, , , udunits2lib}, for details on this package's unit library.

@node Utility, Database, Library, Top
@chapter Unit Utility
@cindex Utility,  unit
@xref{UDUNITS Utility, , , udunits2prog}, for details on this package's unit
utility.

@node Database, Support, Utility, Top
@chapter The Units Database
@cindex database

The database for the UDUNITS-2 package comprises one XML file containing
unit prefixes and four XML files containing unit definitions:

@itemize
@item @uref{../../udunits/udunits2-prefixes.xml,SI unit prefixes}
@item @uref{../../udunits/udunits2-base.xml,SI base units}
@item @uref{../../udunits/udunits2-derived.xml,SI derived units}
@item @uref{../../udunits/udunits2-accepted.xml,Units accepted for use with the SI}
@item @uref{../../udunits/udunits2-common.xml,Non-SI units}
@end itemize

@node Support, Complete Index, Database, Top
@chapter Support for this Package
@cindex support
@cindex package, support

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

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

@node Complete Index, , Support, Top
@unnumbered Index

@printindex cp

@bye