Josh Coalson | 6b05bc5 | 2001-06-08 00:13:21 +0000 | [diff] [blame] | 1 | /* FLAC - Free Lossless Audio Codec |
Josh Coalson | afae69f | 2003-01-02 07:03:16 +0000 | [diff] [blame] | 2 | * Copyright (C) 2001,2002,2003 Josh Coalson |
Josh Coalson | 6b05bc5 | 2001-06-08 00:13:21 +0000 | [diff] [blame] | 3 | * |
| 4 | * This program is part of FLAC; you can redistribute it and/or |
| 5 | * modify it under the terms of the GNU General Public License |
| 6 | * as published by the Free Software Foundation; either version 2 |
| 7 | * of the License, or (at your option) any later version. |
| 8 | * |
| 9 | * This program is distributed in the hope that it will be useful, |
| 10 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 11 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 12 | * GNU General Public License for more details. |
| 13 | * |
| 14 | * You should have received a copy of the GNU General Public License |
| 15 | * along with this program; if not, write to the Free Software |
| 16 | * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. |
| 17 | */ |
| 18 | |
| 19 | |
| 20 | FLAC (http://flac.sourceforge.net/) is an Open Source lossless audio |
| 21 | codec developed by Josh Coalson. |
| 22 | |
Josh Coalson | bc86950 | 2002-06-14 06:36:16 +0000 | [diff] [blame] | 23 | FLAC is comprised of |
| 24 | * `libFLAC', a library which implements reference encoders and |
Josh Coalson | 0c3524c | 2002-08-22 04:21:54 +0000 | [diff] [blame] | 25 | decoders, and a metadata interface |
Josh Coalson | bc86950 | 2002-06-14 06:36:16 +0000 | [diff] [blame] | 26 | * `libFLAC++', a C++ object wrapper library around libFLAC |
Josh Coalson | 0c3524c | 2002-08-22 04:21:54 +0000 | [diff] [blame] | 27 | * `libOggFLAC' and `libOggFLAC++', which provide encoders and |
| 28 | decoders for FLAC streams in an Ogg container |
| 29 | * `flac', a command-line program for encoding and decoding files |
| 30 | * `metaflac', a command-line program for editing FLAC metadata |
| 31 | * player plugins for XMMS and Winamp |
| 32 | * user and API documentation |
| 33 | |
| 34 | The libraries (libFLAC, libFLAC++, libOggFLAC, and libOggFLAC++) are |
| 35 | licensed under the GNU Lesser General Public License (LGPL). All other |
| 36 | programs and plugins are licensed under the GNU General Public License |
| 37 | (GPL). The documentation is licensed under the GNU Free Documentation |
| 38 | License (GFDL). |
| 39 | |
Josh Coalson | 6b05bc5 | 2001-06-08 00:13:21 +0000 | [diff] [blame] | 40 | |
Josh Coalson | 310b9ec | 2002-07-31 06:39:21 +0000 | [diff] [blame] | 41 | =============================================================================== |
Josh Coalson | 75d78a3 | 2003-01-08 08:06:53 +0000 | [diff] [blame] | 42 | FLAC - 1.0.5_beta2 - Contents |
Josh Coalson | 310b9ec | 2002-07-31 06:39:21 +0000 | [diff] [blame] | 43 | =============================================================================== |
| 44 | |
| 45 | - Introduction |
| 46 | - Building in a GNU environment |
| 47 | - Building with Makefile.lite |
| 48 | - Building with MSVC |
| 49 | - Building on Mac OS X |
| 50 | - Note to embedded developers |
| 51 | |
| 52 | |
| 53 | =============================================================================== |
| 54 | Introduction |
| 55 | =============================================================================== |
Josh Coalson | bb7f6b9 | 2000-12-10 04:09:52 +0000 | [diff] [blame] | 56 | |
Josh Coalson | f2be7c3 | 2003-01-03 00:18:15 +0000 | [diff] [blame] | 57 | @@@@ NOTE @@@@ |
| 58 | This is a beta release. The CUESHEET metadata block specification has not |
| 59 | been finalized. |
| 60 | |
Josh Coalson | 6b05bc5 | 2001-06-08 00:13:21 +0000 | [diff] [blame] | 61 | This is the source release for the FLAC project. See |
Josh Coalson | bb7f6b9 | 2000-12-10 04:09:52 +0000 | [diff] [blame] | 62 | |
| 63 | doc/index.html |
| 64 | |
| 65 | for full documentation. |
| 66 | |
| 67 | A brief description of the directory tree: |
| 68 | |
Josh Coalson | 917df86 | 2002-07-03 07:39:05 +0000 | [diff] [blame] | 69 | doc/ the HTML documentation |
| 70 | flac.pbproj/ the Mac OS X Project Builder project |
| 71 | include/ public include files for libFLAC and libFLAC++ |
| 72 | man/ the man page for `flac' |
| 73 | src/ the source code and private headers |
| 74 | test/ the test scripts |
Josh Coalson | bb7f6b9 | 2000-12-10 04:09:52 +0000 | [diff] [blame] | 75 | |
| 76 | |
Josh Coalson | 310b9ec | 2002-07-31 06:39:21 +0000 | [diff] [blame] | 77 | =============================================================================== |
Josh Coalson | bb7f6b9 | 2000-12-10 04:09:52 +0000 | [diff] [blame] | 78 | Building in a GNU environment |
Josh Coalson | 310b9ec | 2002-07-31 06:39:21 +0000 | [diff] [blame] | 79 | =============================================================================== |
Josh Coalson | bb7f6b9 | 2000-12-10 04:09:52 +0000 | [diff] [blame] | 80 | |
Josh Coalson | 172ac00 | 2001-10-31 18:30:19 +0000 | [diff] [blame] | 81 | FLAC uses autoconf and libtool for configuring and building. |
| 82 | Better documentation for these will be forthcoming, but in |
| 83 | general, this should work: |
Josh Coalson | bb7f6b9 | 2000-12-10 04:09:52 +0000 | [diff] [blame] | 84 | |
Josh Coalson | c220cf4 | 2002-08-23 06:41:31 +0000 | [diff] [blame] | 85 | ./configure && make && make check && make install |
| 86 | |
| 87 | The 'make check' step is optional; omit it to skip all the tests, |
Josh Coalson | ccea6aa | 2002-12-17 08:14:42 +0000 | [diff] [blame] | 88 | which can take several hours and use around 70-80 megs of disk space. |
Josh Coalson | bfe42f1 | 2000-12-22 22:42:25 +0000 | [diff] [blame] | 89 | |
Josh Coalson | 917df86 | 2002-07-03 07:39:05 +0000 | [diff] [blame] | 90 | NOTE: Despite our best efforts it's entirely possible to have |
| 91 | problems when using older versions of autoconf, automake, or |
| 92 | libtool. If you have the latest versions and still can't get it |
| 93 | to work, see the next section on Makefile.lite. |
Josh Coalson | 0403256 | 2001-07-20 23:43:15 +0000 | [diff] [blame] | 94 | |
Josh Coalson | 3643db3 | 2001-07-18 00:23:06 +0000 | [diff] [blame] | 95 | There are a few FLAC-specific arguments you can give to |
| 96 | `configure': |
| 97 | |
| 98 | --enable-debug : Builds everything with debug symbols and some |
| 99 | extra (and more verbose) error checking. |
| 100 | |
| 101 | --disable-asm-optimizations : Disables the compilation of the |
| 102 | assembly routines. Many routines have assembly versions for |
| 103 | speed and `configure' is pretty good about knowing what is |
| 104 | supported, but you can use this option to build only from the |
| 105 | C sources. |
| 106 | |
Josh Coalson | e326848 | 2001-12-04 06:46:12 +0000 | [diff] [blame] | 107 | --enable-sse : If you are building for an x86 CPU that supports |
Josh Coalson | 3643db3 | 2001-07-18 00:23:06 +0000 | [diff] [blame] | 108 | SSE instructions, you can enable some of the faster routines |
| 109 | if your operating system also supports SSE instructions. flac |
| 110 | can tell if the CPU supports the instructions but currently has |
| 111 | no way to test if the OS does, so if it does, you must pass |
| 112 | this argument to configure to use the SSE routines. If flac |
| 113 | crashes when built with this option you will have to go back and |
Josh Coalson | e326848 | 2001-12-04 06:46:12 +0000 | [diff] [blame] | 114 | configure without --enable-sse. Note that |
| 115 | --disable-asm-optimizations implies --disable-sse. |
Josh Coalson | 9e6efb6 | 2001-05-29 18:48:42 +0000 | [diff] [blame] | 116 | |
Josh Coalson | e326848 | 2001-12-04 06:46:12 +0000 | [diff] [blame] | 117 | --enable-3dnow : If you are building for an AMD CPU which has 3DNOW! |
Josh Coalson | c69f878 | 2001-11-13 23:08:22 +0000 | [diff] [blame] | 118 | support, you can use this flag to enable some assembly routines |
| 119 | which use 3DNOW! instructions. There have been some reports that |
| 120 | they may cause flac to crash, which is why it is not turned on |
Josh Coalson | 7140a1c | 2001-11-13 23:11:51 +0000 | [diff] [blame] | 121 | by default. Note that --disable-asm-optimizations overrides |
Josh Coalson | e326848 | 2001-12-04 06:46:12 +0000 | [diff] [blame] | 122 | --enable-3dnow. |
Josh Coalson | c69f878 | 2001-11-13 23:08:22 +0000 | [diff] [blame] | 123 | |
Josh Coalson | 822eef6 | 2002-09-12 06:40:44 +0000 | [diff] [blame] | 124 | --with-ogg= |
| 125 | --with-id3lib= |
| 126 | --with-xmms-prefix= |
| 127 | --with-libiconv-prefix= |
| 128 | Use these if you have these packages but configure can't find them. |
| 129 | |
Josh Coalson | 71fb9ff | 2002-12-03 06:29:10 +0000 | [diff] [blame] | 130 | If you want to build completely from scratch (i.e. starting with just |
| 131 | configure.in and Makefile.am) you should be able to just run 'autogen.sh' |
| 132 | but make sure and read the comments in that file first. |
| 133 | |
Josh Coalson | bb7f6b9 | 2000-12-10 04:09:52 +0000 | [diff] [blame] | 134 | |
Josh Coalson | 310b9ec | 2002-07-31 06:39:21 +0000 | [diff] [blame] | 135 | =============================================================================== |
Josh Coalson | 0403256 | 2001-07-20 23:43:15 +0000 | [diff] [blame] | 136 | Building with Makefile.lite |
Josh Coalson | 310b9ec | 2002-07-31 06:39:21 +0000 | [diff] [blame] | 137 | =============================================================================== |
Josh Coalson | 0403256 | 2001-07-20 23:43:15 +0000 | [diff] [blame] | 138 | |
| 139 | There is a more lightweight build system for do-it-yourself-ers. |
| 140 | It is also useful if configure isn't working, which may be the |
| 141 | case since lately we've had some problems with different versions |
| 142 | of automake and libtool. The Makefile.lite system should work |
Josh Coalson | 71fb9ff | 2002-12-03 06:29:10 +0000 | [diff] [blame] | 143 | on GNU systems with few or no adjustments. |
Josh Coalson | 0403256 | 2001-07-20 23:43:15 +0000 | [diff] [blame] | 144 | |
| 145 | From the top level just 'make -f Makefile.lite'. You can |
| 146 | specify zero or one optional target from 'release', 'debug', |
| 147 | 'test', or 'clean'. The default is 'release'. There is no |
| 148 | 'install' target but everything you need will end up in the |
| 149 | obj/ directory. |
| 150 | |
| 151 | If you are not on an x86 system or you don't have nasm, you |
| 152 | may have to change the DEFINES in src/libFLAC/Makefile.lite. If |
| 153 | you don't have nasm, remove -DFLAC__HAS_NASM. If your target is |
| 154 | not an x86, change -DFLAC__CPU_IA32 to -DFLAC__CPU_UNKNOWN. |
| 155 | |
| 156 | |
Josh Coalson | 310b9ec | 2002-07-31 06:39:21 +0000 | [diff] [blame] | 157 | =============================================================================== |
Josh Coalson | bb7f6b9 | 2000-12-10 04:09:52 +0000 | [diff] [blame] | 158 | Building with MSVC |
Josh Coalson | 310b9ec | 2002-07-31 06:39:21 +0000 | [diff] [blame] | 159 | =============================================================================== |
Josh Coalson | bb7f6b9 | 2000-12-10 04:09:52 +0000 | [diff] [blame] | 160 | |
Josh Coalson | 3a17d3c | 2002-10-18 05:49:44 +0000 | [diff] [blame] | 161 | There are two ways to build with MSVC: |
| 162 | |
| 163 | 1. Project Files |
Josh Coalson | a11d5de | 2002-10-18 06:09:38 +0000 | [diff] [blame] | 164 | ---------------- |
Josh Coalson | 71fb9ff | 2002-12-03 06:29:10 +0000 | [diff] [blame] | 165 | Prerequisite: you must have the Ogg libraries installed as described |
| 166 | later. |
| 167 | |
Josh Coalson | 3a17d3c | 2002-10-18 05:49:44 +0000 | [diff] [blame] | 168 | Prerequisite: you must have nasm installed, and have the environment |
| 169 | variable FLAC_NASM set to the full path to nasmw.exe, e.g |
Josh Coalson | a11d5de | 2002-10-18 06:09:38 +0000 | [diff] [blame] | 170 | |
| 171 | C:\nasm\nasmw.exe |
Josh Coalson | 3a17d3c | 2002-10-18 05:49:44 +0000 | [diff] [blame] | 172 | |
| 173 | To build everything, run Developer Studio, do File|Open Workspace, |
| 174 | and open FLAC.dsw. Switch to the 'Files' tab, select 'all files' |
| 175 | from the tree, do right-mouse-button and 'Set as active project'. |
Josh Coalson | 7d518fd | 2002-10-18 05:57:06 +0000 | [diff] [blame] | 176 | The default build mode will probably be Debug; to change to release |
| 177 | do Build|Set Active Configuration and select 'all - Win32 Release'. |
Josh Coalson | 71fb9ff | 2002-12-03 06:29:10 +0000 | [diff] [blame] | 178 | Then do Project|Build. This will build all libraries both statically |
| 179 | (e.g. obj\debug\lib\libFLAC_static.lib) and as DLLs (e.g. |
| 180 | obj\debug\bin\libFLAC.dll), and it will build all binaries, statically |
| 181 | linked (e.g. obj\debug\bin\flac.exe). |
Josh Coalson | 3a17d3c | 2002-10-18 05:49:44 +0000 | [diff] [blame] | 182 | |
| 183 | 2. nmake |
Josh Coalson | a11d5de | 2002-10-18 06:09:38 +0000 | [diff] [blame] | 184 | -------- |
Josh Coalson | 71fb9ff | 2002-12-03 06:29:10 +0000 | [diff] [blame] | 185 | Prerequisite: you must have the Ogg libraries installed as described |
| 186 | later. |
| 187 | |
Josh Coalson | 3a17d3c | 2002-10-18 05:49:44 +0000 | [diff] [blame] | 188 | Prerequisite: you must have nasm installed and nasmw.exe must be in |
| 189 | your path. |
| 190 | |
| 191 | To build everything, open a Command window, cd to the top-level |
| 192 | directory (where this README is) and do |
| 193 | |
Josh Coalson | a11d5de | 2002-10-18 06:09:38 +0000 | [diff] [blame] | 194 | nmake /f Makefile.vc |
Josh Coalson | 3a17d3c | 2002-10-18 05:49:44 +0000 | [diff] [blame] | 195 | |
| 196 | This will recur into all the source directories in the right order |
| 197 | and build everything. The libraries will be build only as static |
Josh Coalson | a11d5de | 2002-10-18 06:09:38 +0000 | [diff] [blame] | 198 | libs. You need only to install the binaries. To clean up everything |
| 199 | you can do |
Josh Coalson | 3a17d3c | 2002-10-18 05:49:44 +0000 | [diff] [blame] | 200 | |
Josh Coalson | a11d5de | 2002-10-18 06:09:38 +0000 | [diff] [blame] | 201 | nmake /f Makefile.vc clean |
Josh Coalson | 3a17d3c | 2002-10-18 05:49:44 +0000 | [diff] [blame] | 202 | |
| 203 | from the top level directory, or any directory which has a |
| 204 | Makefile.vc |
| 205 | |
| 206 | Everything will end up in the 'obj' directory. DLLs and .exe files |
Josh Coalson | 71fb9ff | 2002-12-03 06:29:10 +0000 | [diff] [blame] | 207 | are all that are needed and can be copied to an installation area and |
Josh Coalson | 3a17d3c | 2002-10-18 05:49:44 +0000 | [diff] [blame] | 208 | added to the PATH. The plugins have to be copied to their appropriate |
Josh Coalson | 7d518fd | 2002-10-18 05:57:06 +0000 | [diff] [blame] | 209 | place in the player area. For Winamp2 this is <winamp2-dir>\Plugins |
| 210 | and for Winamp3 this is <winamp3-dir>\Wacs. |
Josh Coalson | 5676eb1 | 2001-11-09 19:23:50 +0000 | [diff] [blame] | 211 | |
Josh Coalson | 71fb9ff | 2002-12-03 06:29:10 +0000 | [diff] [blame] | 212 | By default the code is configured with Ogg support. Before building FLAC |
| 213 | you will need to get the Ogg source distribution |
| 214 | (see http://xiph.org/ogg/vorbis/download/), build ogg_static.lib (load and |
| 215 | build win32\ogg_static.dsp), copy ogg_static.lib into FLAC's |
| 216 | 'obj\release\lib' directory, and copy the entire include\ogg tree into |
| 217 | FLAC's 'include' directory (so that there is an 'ogg' directory in FLAC's |
| 218 | 'include' directory with the files ogg.h, os_types.h and config_types.h). |
| 219 | |
Josh Coalson | 5676eb1 | 2001-11-09 19:23:50 +0000 | [diff] [blame] | 220 | |
Josh Coalson | 310b9ec | 2002-07-31 06:39:21 +0000 | [diff] [blame] | 221 | =============================================================================== |
Josh Coalson | 5676eb1 | 2001-11-09 19:23:50 +0000 | [diff] [blame] | 222 | Building on Mac OS X |
Josh Coalson | 310b9ec | 2002-07-31 06:39:21 +0000 | [diff] [blame] | 223 | =============================================================================== |
Josh Coalson | 5676eb1 | 2001-11-09 19:23:50 +0000 | [diff] [blame] | 224 | |
Josh Coalson | 71fb9ff | 2002-12-03 06:29:10 +0000 | [diff] [blame] | 225 | If you have Fink, the GNU flow above should work. Otherwise, |
Josh Coalson | b83801e | 2002-03-13 04:11:05 +0000 | [diff] [blame] | 226 | there is a Project Builder project in the top-level source |
Josh Coalson | 5676eb1 | 2001-11-09 19:23:50 +0000 | [diff] [blame] | 227 | directory to build libFLAC and the command-line utilities on |
| 228 | Mac OS X. In a terminal, cd to the top-level directory (the |
| 229 | one that contains this README file) and type: |
| 230 | |
| 231 | pbxbuild -alltargets |
| 232 | |
Josh Coalson | b83801e | 2002-03-13 04:11:05 +0000 | [diff] [blame] | 233 | This will create everything and leave it in the build/ directory. |
| 234 | Don't worry about the rest of the stuff that is in build/ or |
Josh Coalson | 5676eb1 | 2001-11-09 19:23:50 +0000 | [diff] [blame] | 235 | the stuff that was already there before building. |
| 236 | |
| 237 | There currently is no install procedure; you will have to |
| 238 | manually copy the tools to wherever you need them. |
Josh Coalson | 310b9ec | 2002-07-31 06:39:21 +0000 | [diff] [blame] | 239 | |
| 240 | |
| 241 | =============================================================================== |
| 242 | Note to embedded developers |
| 243 | =============================================================================== |
| 244 | |
| 245 | libFLAC has grown larger over time as more functionality has been |
| 246 | included, but much of it may be unnecessary for a particular embedded |
| 247 | implementation. Unused parts may be pruned by some simple editing of |
| 248 | configure.in and src/libFLAC/Makefile.am; the following dependency |
| 249 | graph shows which modules may be pruned without breaking things |
| 250 | further down: |
| 251 | |
| 252 | file_encoder.h |
| 253 | stream_encoder.h |
| 254 | format.h |
| 255 | |
| 256 | file_decoder.h |
| 257 | seekable_stream_decoder.h |
| 258 | stream_decoder.h |
| 259 | format.h |
| 260 | |
| 261 | metadata.h |
| 262 | format.h |
| 263 | |
| 264 | There is a section dedicated to embedded use in the libFLAC API |
| 265 | HTML documentation (see doc/html/api/index.html). |