/* FLAC - Free Lossless Audio Codec
- * Copyright (C) 2001 Josh Coalson
+ * Copyright (C) 2001,2002 Josh Coalson
*
* This program is part of FLAC; you can redistribute it and/or
* modify it under the terms of the GNU General Public License
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 is comprised of
+ * `libFLAC', a library which implements reference encoders and
+ decoders, and a metadata interface
+ * `libFLAC++', a C++ object wrapper library around libFLAC
+ * `libOggFLAC' and `libOggFLAC++', which provide encoders and
+ decoders for FLAC streams in an Ogg container
+ * `flac', a command-line program for encoding and decoding files
+ * `metaflac', a command-line program for editing FLAC metadata
+ * player plugins for XMMS and Winamp
+ * user and API documentation
-===========
-FLAC - 0.10
-===========
+The libraries (libFLAC, libFLAC++, libOggFLAC, and libOggFLAC++) are
+licensed under the GNU Lesser General Public License (LGPL). All other
+programs and plugins are licensed under the GNU General Public License
+(GPL). The documentation is licensed under the GNU Free Documentation
+License (GFDL).
+
+
+===============================================================================
+FLAC - 1.0.4 - 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
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
+general, this should work:
+
+./configure && make && make check && make install
+
+The 'make check' step is optional; omit it to skip all the tests,
+which can take several hours.
+
+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':
+
+--enable-debug : Builds everything with debug symbols and some
+extra (and more verbose) error checking.
+
+--disable-asm-optimizations : Disables the compilation of the
+assembly routines. Many routines have assembly versions for
+speed and `configure' is pretty good about knowing what is
+supported, but you can use this option to build only from the
+C sources.
+
+--enable-sse : If you are building for an x86 CPU that supports
+SSE instructions, you can enable some of the faster routines
+if your operating system also supports SSE instructions. flac
+can tell if the CPU supports the instructions but currently has
+no way to test if the OS does, so if it does, you must pass
+this argument to configure to use the SSE routines. If flac
+crashes when built with this option you will have to go back and
+configure without --enable-sse. Note that
+--disable-asm-optimizations implies --disable-sse.
+
+--enable-3dnow : If you are building for an AMD CPU which has 3DNOW!
+support, you can use this flag to enable some assembly routines
+which use 3DNOW! instructions. There have been some reports that
+they may cause flac to crash, which is why it is not turned on
+by default. Note that --disable-asm-optimizations overrides
+--enable-3dnow.
+
+--with-ogg=
+--with-id3lib=
+--with-xmms-prefix=
+--with-libiconv-prefix=
+Use these if you have these packages but configure can't find them.
+
+
+===============================================================================
+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 adjustments.
+
+From the top level just 'make -f Makefile.lite'. You can
+specify zero or one optional target from 'release', 'debug',
+'test', or 'clean'. The default is 'release'. There is no
+'install' target but everything you need will end up in the
+obj/ directory.
+
+If you are not on an x86 system or you don't have nasm, you
+may have to change the DEFINES in src/libFLAC/Makefile.lite. If
+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
+===============================================================================
-FLAC now uses autoconf and libtool for configuring and
-building. Better documentation for these will be
-forthcoming, but in general, this should work:
+There are two ways to build with MSVC:
+@@@@Prerequisite: Ogg headers/libs
-./configure ; make ; make install
+ 1. Project Files
+ ----------------
+ Prerequisite: you must have nasm installed, and have the environment
+ variable FLAC_NASM set to the full path to nasmw.exe, e.g
-To disable all assembly optimizations, pass the
---disable-asm-optimizations flag to configure.
+ C:\nasm\nasmw.exe
+ To build everything, run Developer Studio, do File|Open Workspace,
+ and open FLAC.dsw. Switch to the 'Files' tab, select 'all files'
+ from the tree, do right-mouse-button and 'Set as active project'.
+ The default build mode will probably be Debug; to change to release
+ do Build|Set Active Configuration and select 'all - Win32 Release'.
+ Then do Project|Build. The libraries will be built as and DLLs and
+ you'll need to install these as well.
-==================
-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.
+ 2. nmake
+ --------
+ Prerequisite: you must have nasm installed and nasmw.exe must be in
+ your path.
+
+ To build everything, open a Command window, cd to the top-level
+ directory (where this README is) and do
+
+ nmake /f Makefile.vc
+
+ This will recur into all the source directories in the right order
+ and build everything. The libraries will be build only as static
+ libs. You need only to install the binaries. To clean up everything
+ you can do
+
+ nmake /f Makefile.vc clean
+
+ from the top level directory, or any directory which has a
+ Makefile.vc
+
+Everything will end up in the 'obj' directory. DLLs and .exe files
+are all that are needed and can be copied to an installation area an
+added to the PATH. The plugins have to be copied to their appropriate
+place in the player area. For Winamp2 this is <winamp2-dir>\Plugins
+and for Winamp3 this is <winamp3-dir>\Wacs.
+
+
+===============================================================================
+Building on Mac OS X
+===============================================================================
+
+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 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).