/* FLAC - Free Lossless Audio Codec
- * Copyright (C) 2001,2002 Josh Coalson
+ * Copyright (C) 2001,2002,2003,2004,2005 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
- * as published by the Free Software Foundation; either version 2
- * of the License, or (at your option) any later version.
+ * This file is part the FLAC project. FLAC is comprised of several
+ * components distributed under difference licenses. The codec libraries
+ * are distributed under Xiph.Org's BSD-like license (see the file
+ * COPYING.Xiph in this distribution). All other programs, libraries, and
+ * plugins are distributed under the GPL (see COPYING.GPL). The documentation
+ * is distributed under the Gnu FDL (see COPYING.FDL). Each file in the
+ * FLAC distribution contains at the top the terms under which it may be
+ * distributed.
*
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+ * Since this particular file is relevant to all components of FLAC,
+ * it may be distributed under the Xiph.Org license, which is the least
+ * restrictive of those mentioned above. See the file COPYING.Xiph in this
+ * distribution.
*/
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)
+ decoders, and a metadata interface
* `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_beta
-============
+ * `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 viewing and editing FLAC
+ metadata
+ * player plugins for XMMS and Winamp
+ * user and API documentation
+
+The libraries (libFLAC, libFLAC++, libOggFLAC, and libOggFLAC++) are
+licensed under Xiph.org's BSD-like license (see COPYING.Xiph). All other
+programs and plugins are licensed under the GNU General Public License
+(see COPYING.GPL). The documentation is licensed under the GNU Free
+Documentation License (see COPYING.FDL).
+
+
+===============================================================================
+FLAC - 1.1.1 - Contents
+===============================================================================
+
+- Introduction
+- Prerequisites
+- 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
- doc/index.html
+ doc/html/index.html
for full documentation.
A brief description of the directory tree:
- doc/ the HTML documentation
- man/ the man page for `flac'
- 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
+
+
+===============================================================================
+Prerequisites
+===============================================================================
+
+To build FLAC with support for Ogg FLAC you must have built and installed
+libogg according to the specific instructions below. You must have
+libogg 1.1.2 or greater, or there will be seeking problems with Ogg FLAC.
+
+If you are building on x86 and want the assembly optimizations, you will
+need to have NASM >= 0.98.30 installed according to the specific instructions
+below.
-=============================
+===============================================================================
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 install
+./configure && make && make check && 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.
+The 'make check' step is optional; omit it to skip all the tests,
+which can take several hours and use around 70-80 megs of disk space.
+Even though it will stop with an explicit message on any failure, it
+does print out a lot of stuff so you might want to capture the output
+to a file if you're having a problem. Also, don't run 'make check'
+as root because it confuses some of the tests.
-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':
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.
+--enable-local-xmms-plugin : Installs the FLAC XMMS plugin in
+$HOME/.xmms/Plugins, instead of the global XMMS plugin area
+(usually /usr/lib/xmms/Input).
+--with-ogg=
+--with-xmms-prefix=
+--with-libiconv-prefix=
+Use these if you have these packages but configure can't find them.
-===========================
+If you want to build completely from scratch (i.e. starting with just
+configure.in and Makefile.am) you should be able to just run 'autogen.sh'
+but make sure and read the comments in that file first.
+
+
+===============================================================================
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.
+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',
not an x86, change -DFLAC__CPU_IA32 to -DFLAC__CPU_UNKNOWN.
-==================
+===============================================================================
Building with MSVC
-==================
+===============================================================================
+
+There are now .dsp projects and a master FLAC.dsw workspace to build
+all the libraries and executables.
+
+Prerequisite: you must have the Ogg libraries installed as described
+later.
+
+Prerequisite: you must have nasm installed, and nasmw.exe must be in
+your PATH, or the path to nasmw.exe must be added to the list of
+directories for executable files in the MSVC global options.
-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 .nasm files.
+To build everything, run Developer Studio, do File|Open Workspace,
+and open FLAC.dsw. Select "Build | Set active configuration..."
+from the menu, then in the dialog, select "All - Win32 Release" (or
+Debug if you prefer). Click "Ok" then hit F7 to build. This will build
+all libraries both statically (e.g. obj\release\lib\libFLAC_static.lib)
+and as DLLs (e.g. obj\release\bin\libFLAC.dll), and it will build all
+binaries, statically linked (e.g. obj\release\bin\flac.exe).
+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 and
+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.
-====================
+By default the code is configured with Ogg support. Before building FLAC
+you will need to get the Ogg source distribution
+(see http://xiph.org/ogg/vorbis/download/), build ogg_static.lib (load and
+build win32\ogg_static.dsp), copy ogg_static.lib into FLAC's
+'obj\release\lib' directory, and copy the entire include\ogg tree into
+FLAC's 'include' directory (so that there is an 'ogg' directory in FLAC's
+'include' directory with the files ogg.h, os_types.h and config_types.h).
+
+
+===============================================================================
Building on Mac OS X
-====================
+===============================================================================
-If you have Fink, the Gnu flow above should work. Otherwise,
+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
Don't worry about the rest of the stuff that is in build/ or
the stuff that was already there before building.
+The Project Builder project requires that you have libiconv and
+libogg in /sw, ala fink. If you don't, you'll need to install
+them somewhere and change the path to them in the Library Paths
+section of several targets.
+
+It also assumes the CPU supports Altivec instructions. If it does
+not, you will also have to add -DFLAC__NO_ASM to the CFLAGS in the
+libFLAC target.
+
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).