start code cleanup
[flac.git] / README
diff --git a/README b/README
index 9c5d8a9..4cb21d9 100644 (file)
--- a/README
+++ b/README
 FLAC (http://flac.sourceforge.net/) is an Open Source lossless audio
 codec developed by Josh Coalson.
 
-FLAC is comprised of 1) `libFLAC', a library which implements
-reference encoders and decoders, licensed under the GNU Lesser
-General Public License (LGPL); 2) `flac', a command-line program for
-encoding and decoding files, licensed under the GNU General public
-License (GPL); 3) `metaflac', a command-line program for editing
-FLAC metadata, licensed under the GPL; 4) player plugins for XMMS
-and Winamp, licensed under the GPL; and 5) documentation, licensed
-under the GNU Free Documentation License.
-
-============
-FLAC - 1.0.2
-============
+FLAC is comprised of
+  * `libFLAC', a library which implements reference encoders and
+    decoders, and a metadata interface, licensed under the GNU
+    Lesser General Public License (LGPL)
+  * `libFLAC++', a C++ object wrapper library around libFLAC
+  * `flac', a command-line program for encoding and decoding files,
+    licensed under the GNU General public License (GPL)
+  * `metaflac', a command-line program for editing FLAC metadata,
+    licensed under the GPL
+  * player plugins for XMMS and Winamp, licensed under the GPL
+  * documentation, licensed under the GNU Free Documentation License.
+
+===============================================================================
+FLAC - 1.0.3 - Contents
+===============================================================================
+
+- Introduction
+- Building in a GNU environment
+- Building with Makefile.lite
+- Building with MSVC
+- Building on Mac OS X
+- Note to embedded developers
+
+
+===============================================================================
+Introduction
+===============================================================================
 
 This is the source release for the FLAC project.  See
 
@@ -41,15 +56,17 @@ for full documentation.
 
 A brief description of the directory tree:
 
-       doc/       the HTML documentation
-       include/   public include files for libFLAC
-       src/       the source code and private headers
-       test/      the test scripts
+       doc/          the HTML documentation
+       flac.pbproj/  the Mac OS X Project Builder project
+       include/      public include files for libFLAC and libFLAC++
+       man/          the man page for `flac'
+       src/          the source code and private headers
+       test/         the test scripts
 
 
-=============================
+===============================================================================
 Building in a GNU environment
-=============================
+===============================================================================
 
 FLAC uses autoconf and libtool for configuring and building.
 Better documentation for these will be forthcoming, but in
@@ -57,14 +74,10 @@ general, this should work:
 
 ./configure && make && make install
 
-NOTE: automake 1.5 has a bug which will affect the x86 assembly
-part of the build.  If you have automake 1.5 and have x86
-assembly optimizations turned on, you will need to get a newer
-version of automake or patch your /usr/bin/automake using the
-included 'automake-1.5.patch' file.
-
-If you still can't get it to work, see the next section on
-Makefile.lite.
+NOTE: Despite our best efforts it's entirely possible to have
+problems when using older versions of autoconf, automake, or
+libtool.  If you have the latest versions and still can't get it
+to work, see the next section on Makefile.lite.
 
 There are a few FLAC-specific arguments you can give to
 `configure':
@@ -96,15 +109,15 @@ by default.  Note that --disable-asm-optimizations overrides
 --enable-3dnow.
 
 
-===========================
+===============================================================================
 Building with Makefile.lite
-===========================
+===============================================================================
 
 There is a more lightweight build system for do-it-yourself-ers.
 It is also useful if configure isn't working, which may be the
 case since lately we've had some problems with different versions
 of automake and libtool.  The Makefile.lite system should work
-on Gnu systems with few or no minor adjustments.
+on Gnu systems with few or no adjustments.
 
 From the top level just 'make -f Makefile.lite'.  You can
 specify zero or one optional target from 'release', 'debug',
@@ -118,33 +131,61 @@ you don't have nasm, remove -DFLAC__HAS_NASM.  If your target is
 not an x86, change -DFLAC__CPU_IA32 to -DFLAC__CPU_UNKNOWN.
 
 
-==================
+===============================================================================
 Building with MSVC
-==================
+===============================================================================
 
 There is no overall make system for MSVC but the individual
 source directories with a 'Makefile.vc' file in them allow
 building with MSVC.  Just 'nmake /f Makefile.vc'.  Currently
 the Makefile.vc for libFLAC is hardcoded to use nasm.  If
 you don't have nasm, or don't want any assembly optimizations,
-edit the makefile, adding '/D FLAC__NO_ASM' and delete the
-rules which compile the .s files.
+edit the makefile, adding '/D FLAC__NO_ASM', and delete the
+rules which compile the .nasm files.
 
 
-====================
+===============================================================================
 Building on Mac OS X
-====================
+===============================================================================
 
-There is a Project Builder project in the top-level source
+If you have Fink, the Gnu flow above should work.  Otherwise,
+there is a Project Builder project in the top-level source
 directory to build libFLAC and the command-line utilities on
 Mac OS X.  In a terminal, cd to the top-level directory (the
 one that contains this README file) and type:
 
        pbxbuild -alltargets
 
-This will create everything and leave it in build/ directory.
-Don't worry about the rest of the stuff that is in build or
+This will create everything and leave it in the build/ directory.
+Don't worry about the rest of the stuff that is in build/ or
 the stuff that was already there before building.
 
 There currently is no install procedure; you will have to
 manually copy the tools to wherever you need them.
+
+
+===============================================================================
+Note to embedded developers
+===============================================================================
+
+libFLAC has grown larger over time as more functionality has been
+included, but much of it may be unnecessary for a particular embedded
+implementation.  Unused parts may be pruned by some simple editing of
+configure.in and src/libFLAC/Makefile.am; the following dependency
+graph shows which modules may be pruned without breaking things
+further down:
+
+file_encoder.h
+       stream_encoder.h
+               format.h
+
+file_decoder.h
+       seekable_stream_decoder.h
+               stream_decoder.h
+                       format.h
+
+metadata.h
+       format.h
+
+There is a section dedicated to embedded use in the libFLAC API
+HTML documentation (see doc/html/api/index.html).