=================================================================
            libdmtx - Open Source Data Matrix Software
=================================================================

               libdmtx README file (all platforms)

This summary of the libdmtx package applies generally to all
platforms. For instructions regarding your specific platform
please also read the README.xxx file in this directory that
matches your system (e.g., README.linux, README.windows,
README.osx, etc...).


1. Introduction
-----------------------------------------------------------------

libdmtx is open source software for reading and writing Data
Matrix barcodes on Linux, Unix, OS X, Windows, and some mobile
devices. At its core libdmtx is a shared library, allowing C/C++
programs to use its capabilities without restrictions or
overhead.

The included utility programs, dmtxread and dmtxwrite, provide
the official command line interface to libdmtx, and also serve as
a good reference for programmers who wish to write their own
programs that interact with libdmtx. All of the software in the
libdmtx package is distributed under the LGPL and can be used
freely under its terms.


2. Package Components
-----------------------------------------------------------------

libdmtx serves a diverse audience and contains several unrelated
components, many of which may not be useful to you. Components
fall into one of four categories:

  * Core library      (useful to all libdmtx users)
  * Utility programs  (useful to command line users)
  * Test programs     (useful to libdmtx developers)
  * Language Wrappers (useful to non-C/C++ developers)

The default installation will compile and install the core
library and all three command line utilities. The test programs
will compile by performing an additional "make check", and the
language wrappers are built using instructions found in their
specific directories.

Users who only want the core library can disable the command line
utilities by passing any combination of the following parameters
to "./configure":

  --disable-dmtxread
  --disable-dmtxwrite
  --disable-dmtxquery

This is often useful in reducing compile times and avoiding
unnecessary dependencies. Do note, however, that these utilities
provide a convenient way to test the library and learn its
behavior, so their inclusion is recommended if possible.

Appendix A. at the end of this file provides a full list of the
package components and their properties.


3. Installation
-----------------------------------------------------------------

libdmtx uses GNU Autotools so installation should be familiar to
free software veterans. If your platform cannot easily run the
Autotools scripts (e.g., MS Visual Studio) then refer to the
appropriate platform-specific README.xxx located in this
directory for alternate instructions.

Ideally, the following 3 steps will compile and install libdmtx
on your system:

  $ ./configure
  $ make
  $ sudo make install

However, nobody is ever that lucky. Some details are provided
below for when things go wrong or if you want to customize beyond
the defaults.

Details on "configure" step
----------------------------------------
If you obtained libdmtx from Subversion you may have received an
error like "./configure: No such file or directory". Run this
command and try again:

  $ ./autogen.sh

The autogen.sh command requires autoconf, automake, libtool, and
pkgconfig to be installed on your system.

The configure script offers many options for customizing the
build process, many of which are described in the INSTALL file in
this directory. If the INSTALL file does not exist then you may
need to run the "./autogen.sh" step first. Examples of common
customizations include:

  $ ./configure CC=/usr/local2/bin/gcc
  $ ./configure --prefix=/your/custom/path
  $ ./configure --disable-dmtxread --disable-dmtxwrite

Details on "make" step
----------------------------------------
Errors encountered during the "make" step are often a result of
missing software dependencies. These dependencies are listed in
Appendix A. in this file. Install any missing software and start
over.

Details on "sudo make install" step
----------------------------------------
If the 'sudo' command is not configured on your system then
alternatively you can yell "Yeeehaww!" as you log in as root and
run this instead:

  $ make install

And finally...
----------------------------------------
If you want to verify that everything is working properly you can
optionally build the test programs like this:

  $ make check

This command will not perform any tests, but will build the
programs that contain the test logic: simpletest, unittest,
and gltest. Note that the gltest program has significant
dependencies due to its graphical nature, and does not provide
significant utility unless you are testing the library decoding
internals.


4. Basic Usage
-----------------------------------------------------------------

New users are encouraged to read the man pages for the library
and command line utilities. However, here are a few simple cases
to get you started:

The dmtxwrite utility turns messages into a barcode images.
Messages are passed to dmtxwrite via file or standard input, and
the output images are written to file or standard output. The
following examples all produce equivalent results:

  $ echo -n 123456 | dmtxwrite > image.png
  $ echo -n 123456 | dmtxwrite -o image.png
  $ echo -n 123456 > message.txt; dmtxwrite message.txt > image.png
  $ dmtxwrite <(echo -n 123456) -o image.png

Conversely,the dmtxread utility turns barcode images into
messages. Images are passed to dmtxread via standard input or
file, and the output is written to standard output. The following
examples produce equivalent results:

  $ dmtxread -n image.png
  $ cat image.png | dmtxread -n

Other typical cases:

  $ dmtxread -n -N1 image1.png image2.png image3.png
  $ dmtxread -n -N1 -m500 image.png

You can even combine the utilities like this:

  $ echo 'Hello, world!' | dmtxwrite | dmtxread
  Hello, world!

  $ dmtxread image1.png | dmtxwrite -o image2.png

Note in this last example that the resulting image2.png might
look different than image1.png. Both barcodes will contain an
identical message, but the shape of the barcode and the internal
representation of the encoded bits may be completely different.


5. Contact
-----------------------------------------------------------------

Official website:      http://www.libdmtx.org
SourceForge.net page:  http://www.sourceforge.net/projects/libdmtx
OhLoh.net page:        https://www.ohloh.net/projects/libdmtx
Open mailing list:     libdmtx-open_discussion@lists.sourceforge.net


Appendix A. Full Listing of libdmtx Components
-----------------------------------------------------------------

Name:        libdmtx
Type:        Core library
Description: Data Matrix encoding/decoding logic
Location:    libdmtx
Build:       make
Requires:    No dependencies

-----------------------------------

Name:        dmtxread
Type:        Utility program
Description: Read Data Matrix barcodes from the command line
Location:    libdmtx/util/dmtxread
Build:       make
Requires:    GraphicsMagick
Disable:     ./configure --disable-dmtxread

-----------------------------------

Name:        dmtxwrite
Type:        Utility program
Description: Create Data Matrix barcodes from the command line
Location:    libdmtx/util/dmtxwrite
Build:       make
Requires:    libpng
Disable:     ./configure --disable-dmtxwrite

-----------------------------------

Name:        dmtxquery
Type:        Utility program (currently non functional)
Description: Query and merge scan results from dmtxread utility
Location:    libdmtx/util/dmtxquery
Build:       make
Requires:    No dependencies
Disable:     Currently not possible

-----------------------------------

Name:        pydmtx
Type:        Language wrapper
Description: Python libdmtx wrapper
Location:    libdmtx/wrappers/python
Build:       See INSTALL file in libdmtx/wrappers/python directory
Requires:    python, pil
Disable:     Not included in default build

-----------------------------------

Name:        libdmtx-php
Type:        Language wrapper
Description: PHP libdmtx wrapper
Location:    libdmtx/wrappers/php
Build:       See INSTALL file in libdmtx/wrappers/php directory
Requires:    php, php-cli, php-common
Disable:     Not included in default build

-----------------------------------

Name:        libdmtx Cocoa wrapper
Type:        Language wrapper
Description: Cocoa libdmtx wrapper
Location:    libdmtx/wrappers/cocoa
Build:       See INSTALL file in libdmtx/wrappers/cocoa directory
Requires:    OS X
Disable:     Not included in default build

-----------------------------------

Name:        gltest
Type:        test program
Description: Scan simulated camera input from OpenGL in realtime
Location:    libdmtx/
Build:       make check
Requires:    mesa-libGL, mesa-libGLU, SDL, libpng
Disable:     Not included in default build

-----------------------------------

Name:        simpletest
Type:        test program
Description: Simple round-trip encoding and decoding test
Build:       make check
Requires:    No dependencies
Disable:     Not included in default build

-----------------------------------

Name:        unittest
Type:        test program
Description: Unit test program
Build:       make check
Requires:    No dependencies
Disable:     Not included in default build

-----------------------------------
