include/share/endswap.h : Fix default ENDSWAP_16.
[flac.git] / README
diff --git a/README b/README
index bdc7a28..b74725d 100644 (file)
--- a/README
+++ b/README
 /* FLAC - Free Lossless Audio Codec
- * Copyright (C) 2001,2002,2003  Josh Coalson
+ * Copyright (C) 2001-2009  Josh Coalson
+ * Copyright (C) 2011-2013  Xiph.Org Foundation
  *
- * 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 different 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 LGPL or GPL (see COPYING.LGPL and
+ * 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 (http://flac.sourceforge.net/) is an Open Source lossless audio
-codec developed by Josh Coalson.
+FLAC is an Open Source lossless audio codec developed by Josh Coalson from 2001
+to 2009.
+
+From January 2012 FLAC is being maintained by Erik de Castro Lopo under the
+auspices of the Xiph.org Foundation.
 
 FLAC is comprised of
   * `libFLAC', a library which implements reference encoders and
-    decoders, and a metadata interface
+    decoders for native FLAC and Ogg FLAC, 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
+  * `metaflac', a command-line program for viewing and editing FLAC
+    metadata
+  * player plugin for XMMS
   * user and API documentation
 
-The libraries (libFLAC, libFLAC++, libOggFLAC, and libOggFLAC++) are
-licensed under the GNU Lesser General Public License (LGPL).  All other
+The libraries (libFLAC, libFLAC++) 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
-(GPL).  The documentation is licensed under the GNU Free Documentation
-License (GFDL).
+(see COPYING.GPL).  The documentation is licensed under the GNU Free
+Documentation License (see COPYING.FDL).
 
 
 ===============================================================================
-FLAC - 1.0.5_beta2 - Contents
+FLAC - 1.3.0 - Contents
 ===============================================================================
 
 - Introduction
+- Prerequisites
+- Note to embedded developers
 - Building in a GNU environment
 - Building with Makefile.lite
 - Building with MSVC
 - Building on Mac OS X
-- Note to embedded developers
 
 
 ===============================================================================
 Introduction
 ===============================================================================
 
-@@@@ NOTE @@@@
-This is a beta release.  The CUESHEET metadata block specification has not
-been finalized.
-
 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
-       flac.pbproj/  the Mac OS X Project Builder project
+       examples/     example programs demonstrating the use of libFLAC and libFLAC++
        include/      public include files for libFLAC and libFLAC++
-       man/          the man page for `flac'
+       man/          the man pages for `flac' and `metaflac'
        src/          the source code and private headers
        test/         the test scripts
 
+If you have questions about building FLAC that this document does not answer,
+please submit them at the following tracker so this document can be improved:
+
+       https://sourceforge.net/p/flac/support-requests/
+
+
+===============================================================================
+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.
+
+
+===============================================================================
+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.ac and src/libFLAC/Makefile.am; the following dependency
+graph shows which modules may be pruned without breaking things
+further down:
+
+metadata.h
+       stream_decoder.h
+       format.h
+
+stream_encoder.h
+       stream_decoder.h
+       format.h
+
+stream_decoder.h
+       format.h
+
+In other words, for pure decoding applications, both the stream encoder
+and metadata editing interfaces can be safely removed.
+
+There is a section dedicated to embedded use in the libFLAC API
+HTML documentation (see doc/html/api/index.html).
+
+Also, there are several places in the libFLAC code with comments marked
+with "OPT:" where a #define can be changed to enable code that might be
+faster on a specific platform.  Experimenting with these can yield faster
+binaries.
+
 
 ===============================================================================
 Building in a GNU environment
@@ -86,6 +138,10 @@ general, this should work:
 
 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.
 
 NOTE: Despite our best efforts it's entirely possible to have
 problems when using older versions of autoconf, automake, or
@@ -102,7 +158,7 @@ extra (and more verbose) error checking.
 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.
+C sources.  May be necessary for building on OS X (Intel).
 
 --enable-sse : If you are building for an x86 CPU that supports
 SSE instructions, you can enable some of the faster routines
@@ -119,13 +175,12 @@ $HOME/.xmms/Plugins, instead of the global XMMS plugin area
 (usually /usr/lib/xmms/Input).
 
 --with-ogg=
---with-id3lib=
 --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'
+configure.ac and Makefile.am) you should be able to just run 'autogen.sh'
 but make sure and read the comments in that file first.
 
 
@@ -155,108 +210,45 @@ not an x86, change -DFLAC__CPU_IA32 to -DFLAC__CPU_UNKNOWN.
 Building with MSVC
 ===============================================================================
 
-There are two ways to build with MSVC:
-
-  1. Project Files
-  ----------------
-  Prerequisite: you must have the Ogg libraries installed as described
-  later.
-
-  Prerequisite: you must have nasm installed, and have the environment
-  variable FLAC_NASM set to the full path to nasmw.exe, e.g
-
-    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.  This will build all libraries both statically
-  (e.g. obj\debug\lib\libFLAC_static.lib) and as DLLs (e.g.
-  obj\debug\bin\libFLAC.dll), and it will build all binaries, statically
-  linked (e.g. obj\debug\bin\flac.exe).
-
-  2. nmake
-  --------
-  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.
+There are .vcproj projects and a master FLAC.sln solution to build all
+the libraries and executables with MSVC 2005 or newer.
 
-  To build everything, open a Command window, cd to the top-level
-  directory (where this README is) and do
+Prerequisite: you must have the Ogg libraries installed as described
+later.
 
-    nmake /f Makefile.vc
+Prerequisite: you must have nasm installed, and nasm.exe must be in
+your PATH, or the path to nasm.exe must be added to the list of
+directories for executable files in the MSVC global options.
 
-  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
+To build everything, run Visual Studio, do File|Open and open FLAC.sln.
+From the dropdown in the toolbar, select "Release" instead of "Debug",
+then do Build|Build Solution.
 
-    nmake /f Makefile.vc clean
+This will build all libraries both statically (e.g.
+objs\release\lib\libFLAC_static.lib) and as DLLs (e.g.
+objs\release\lib\libFLAC.dll), and it will build all binaries, statically
+linked (e.g. objs\release\bin\flac.exe).
 
-  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
+Everything will end up in the "objs" 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
-and for Winamp3 this is <winamp3-dir>\Wacs.
+added to the PATH.
 
-By default the code is configured with Ogg support.  Before building FLAC
+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
+(see http://xiph.org/downloads/), build libogg_static.lib (load
+win32\libogg_static.sln, change solution configuration to "Release" and
+code generation to "Multi-threaded (/MT)", then build), copy libogg_static.lib
+into FLAC's 'objs\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,
-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.
+If you want to build without Ogg support, instead edit all .vcproj files
+and remove any "FLAC__HAS_OGG" definitions.
 
 
 ===============================================================================
-Note to embedded developers
+Building on Mac OS X
 ===============================================================================
 
-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).
+If you have Fink or a recent version of OS X with the proper autotools,
+the GNU flow above should work.