minor formatting
[flac.git] / README
diff --git a/README b/README
index 55f9301..a271b8b 100644 (file)
--- a/README
+++ b/README
@@ -1,19 +1,19 @@
 /* FLAC - Free Lossless Audio Codec
- * Copyright (C) 2001,2002  Josh Coalson
+ * Copyright (C) 2001,2002,2003,2004  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.
  */
 
 
@@ -27,19 +27,20 @@ FLAC is comprised of
   * `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
+  * `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 the GNU Lesser General Public License (LGPL).  All other
+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.4 - Contents
+FLAC - 1.1.1 - Contents
 ===============================================================================
 
 - Introduction
@@ -56,7 +57,7 @@ Introduction
 
 This is the source release for the FLAC project.  See
 
-       doc/index.html
+       doc/html/index.html
 
 for full documentation.
 
@@ -81,7 +82,11 @@ 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.
+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
@@ -110,12 +115,9 @@ 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.
+--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-id3lib=
@@ -123,6 +125,10 @@ by default.  Note that --disable-asm-optimizations overrides
 --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
@@ -132,7 +138,7 @@ 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',
@@ -150,51 +156,43 @@ not an x86, change -DFLAC__CPU_IA32 to -DFLAC__CPU_UNKNOWN.
 Building with MSVC
 ===============================================================================
 
-There are two ways to build with MSVC:
-@@@@Prerequisite: Ogg headers/libs
-
-  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
-  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 both .libs and DLLs.
-
-  2. nmake
-  Prerequisite: you must have nasm installed and nasmw.exe must be in
-  your path.
+There are now .dsp projects and a master FLAC.dsw workspace to build
+all the libraries and executables.
 
-  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 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.
 
-  This will recur into all the source directories in the right order
-  and build everything.  The libraries will be build only as static
-  libs.  To clean up everything you can do
+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).
 
-  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
+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
-and for Winamp3 this is <winamp3-dir>\Wacs.
+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
@@ -206,6 +204,15 @@ 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.
 
+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.