cannam@86: /* FLAC - Free Lossless Audio Codec cannam@86: * Copyright (C) 2001,2002,2003,2004,2005,2006,2007 Josh Coalson cannam@86: * cannam@86: * This file is part the FLAC project. FLAC is comprised of several cannam@86: * components distributed under difference licenses. The codec libraries cannam@86: * are distributed under Xiph.Org's BSD-like license (see the file cannam@86: * COPYING.Xiph in this distribution). All other programs, libraries, and cannam@86: * plugins are distributed under the LGPL or GPL (see COPYING.LGPL and cannam@86: * COPYING.GPL). The documentation is distributed under the Gnu FDL (see cannam@86: * COPYING.FDL). Each file in the FLAC distribution contains at the top the cannam@86: * terms under which it may be distributed. cannam@86: * cannam@86: * Since this particular file is relevant to all components of FLAC, cannam@86: * it may be distributed under the Xiph.Org license, which is the least cannam@86: * restrictive of those mentioned above. See the file COPYING.Xiph in this cannam@86: * distribution. cannam@86: */ cannam@86: cannam@86: cannam@86: FLAC (http://flac.sourceforge.net/) is an Open Source lossless audio cannam@86: codec developed by Josh Coalson. cannam@86: cannam@86: FLAC is comprised of cannam@86: * `libFLAC', a library which implements reference encoders and cannam@86: decoders for native FLAC and Ogg FLAC, and a metadata interface cannam@86: * `libFLAC++', a C++ object wrapper library around libFLAC cannam@86: * `flac', a command-line program for encoding and decoding files cannam@86: * `metaflac', a command-line program for viewing and editing FLAC cannam@86: metadata cannam@86: * player plugins for XMMS and Winamp cannam@86: * user and API documentation cannam@86: cannam@86: The libraries (libFLAC, libFLAC++) are cannam@86: licensed under Xiph.org's BSD-like license (see COPYING.Xiph). All other cannam@86: programs and plugins are licensed under the GNU General Public License cannam@86: (see COPYING.GPL). The documentation is licensed under the GNU Free cannam@86: Documentation License (see COPYING.FDL). cannam@86: cannam@86: cannam@86: =============================================================================== cannam@86: FLAC - 1.2.1 - Contents cannam@86: =============================================================================== cannam@86: cannam@86: - Introduction cannam@86: - Prerequisites cannam@86: - Note to embedded developers cannam@86: - Building in a GNU environment cannam@86: - Building with Makefile.lite cannam@86: - Building with MSVC cannam@86: - Building on Mac OS X cannam@86: cannam@86: cannam@86: =============================================================================== cannam@86: Introduction cannam@86: =============================================================================== cannam@86: cannam@86: This is the source release for the FLAC project. See cannam@86: cannam@86: doc/html/index.html cannam@86: cannam@86: for full documentation. cannam@86: cannam@86: A brief description of the directory tree: cannam@86: cannam@86: doc/ the HTML documentation cannam@86: include/ public include files for libFLAC and libFLAC++ cannam@86: man/ the man page for `flac' cannam@86: src/ the source code and private headers cannam@86: test/ the test scripts cannam@86: cannam@86: cannam@86: =============================================================================== cannam@86: Prerequisites cannam@86: =============================================================================== cannam@86: cannam@86: To build FLAC with support for Ogg FLAC you must have built and installed cannam@86: libogg according to the specific instructions below. You must have cannam@86: libogg 1.1.2 or greater, or there will be seeking problems with Ogg FLAC. cannam@86: cannam@86: If you are building on x86 and want the assembly optimizations, you will cannam@86: need to have NASM >= 0.98.30 installed according to the specific instructions cannam@86: below. cannam@86: cannam@86: cannam@86: =============================================================================== cannam@86: Note to embedded developers cannam@86: =============================================================================== cannam@86: cannam@86: libFLAC has grown larger over time as more functionality has been cannam@86: included, but much of it may be unnecessary for a particular embedded cannam@86: implementation. Unused parts may be pruned by some simple editing of cannam@86: configure.in and src/libFLAC/Makefile.am; the following dependency cannam@86: graph shows which modules may be pruned without breaking things cannam@86: further down: cannam@86: cannam@86: metadata.h cannam@86: stream_decoder.h cannam@86: format.h cannam@86: cannam@86: stream_encoder.h cannam@86: stream_decoder.h cannam@86: format.h cannam@86: cannam@86: stream_decoder.h cannam@86: format.h cannam@86: cannam@86: In other words, for pure decoding applications, both the stream encoder cannam@86: and metadata editing interfaces can be safely removed. cannam@86: cannam@86: There is a section dedicated to embedded use in the libFLAC API cannam@86: HTML documentation (see doc/html/api/index.html). cannam@86: cannam@86: Also, there are several places in the libFLAC code with comments marked cannam@86: with "OPT:" where a #define can be changed to enable code that might be cannam@86: faster on a specific platform. Experimenting with these can yield faster cannam@86: binaries. cannam@86: cannam@86: cannam@86: =============================================================================== cannam@86: Building in a GNU environment cannam@86: =============================================================================== cannam@86: cannam@86: FLAC uses autoconf and libtool for configuring and building. cannam@86: Better documentation for these will be forthcoming, but in cannam@86: general, this should work: cannam@86: cannam@86: ./configure && make && make check && make install cannam@86: cannam@86: The 'make check' step is optional; omit it to skip all the tests, cannam@86: which can take several hours and use around 70-80 megs of disk space. cannam@86: Even though it will stop with an explicit message on any failure, it cannam@86: does print out a lot of stuff so you might want to capture the output cannam@86: to a file if you're having a problem. Also, don't run 'make check' cannam@86: as root because it confuses some of the tests. cannam@86: cannam@86: NOTE: Despite our best efforts it's entirely possible to have cannam@86: problems when using older versions of autoconf, automake, or cannam@86: libtool. If you have the latest versions and still can't get it cannam@86: to work, see the next section on Makefile.lite. cannam@86: cannam@86: There are a few FLAC-specific arguments you can give to cannam@86: `configure': cannam@86: cannam@86: --enable-debug : Builds everything with debug symbols and some cannam@86: extra (and more verbose) error checking. cannam@86: cannam@86: --disable-asm-optimizations : Disables the compilation of the cannam@86: assembly routines. Many routines have assembly versions for cannam@86: speed and `configure' is pretty good about knowing what is cannam@86: supported, but you can use this option to build only from the cannam@86: C sources. May be necessary for building on OS X (Intel) cannam@86: cannam@86: --enable-sse : If you are building for an x86 CPU that supports cannam@86: SSE instructions, you can enable some of the faster routines cannam@86: if your operating system also supports SSE instructions. flac cannam@86: can tell if the CPU supports the instructions but currently has cannam@86: no way to test if the OS does, so if it does, you must pass cannam@86: this argument to configure to use the SSE routines. If flac cannam@86: crashes when built with this option you will have to go back and cannam@86: configure without --enable-sse. Note that cannam@86: --disable-asm-optimizations implies --disable-sse. cannam@86: cannam@86: --enable-local-xmms-plugin : Installs the FLAC XMMS plugin in cannam@86: $HOME/.xmms/Plugins, instead of the global XMMS plugin area cannam@86: (usually /usr/lib/xmms/Input). cannam@86: cannam@86: --with-ogg= cannam@86: --with-xmms-prefix= cannam@86: --with-libiconv-prefix= cannam@86: Use these if you have these packages but configure can't find them. cannam@86: cannam@86: If you want to build completely from scratch (i.e. starting with just cannam@86: configure.in and Makefile.am) you should be able to just run 'autogen.sh' cannam@86: but make sure and read the comments in that file first. cannam@86: cannam@86: cannam@86: =============================================================================== cannam@86: Building with Makefile.lite cannam@86: =============================================================================== cannam@86: cannam@86: There is a more lightweight build system for do-it-yourself-ers. cannam@86: It is also useful if configure isn't working, which may be the cannam@86: case since lately we've had some problems with different versions cannam@86: of automake and libtool. The Makefile.lite system should work cannam@86: on GNU systems with few or no adjustments. cannam@86: cannam@86: From the top level just 'make -f Makefile.lite'. You can cannam@86: specify zero or one optional target from 'release', 'debug', cannam@86: 'test', or 'clean'. The default is 'release'. There is no cannam@86: 'install' target but everything you need will end up in the cannam@86: obj/ directory. cannam@86: cannam@86: If you are not on an x86 system or you don't have nasm, you cannam@86: may have to change the DEFINES in src/libFLAC/Makefile.lite. If cannam@86: you don't have nasm, remove -DFLAC__HAS_NASM. If your target is cannam@86: not an x86, change -DFLAC__CPU_IA32 to -DFLAC__CPU_UNKNOWN. cannam@86: cannam@86: cannam@86: =============================================================================== cannam@86: Building with MSVC cannam@86: =============================================================================== cannam@86: cannam@86: There are .dsp projects and a master FLAC.dsw workspace to build all cannam@86: the libraries and executables with MSVC6. There are also .vcproj cannam@86: projects and a master FLAC.sln solution to build all the libraries and cannam@86: executables with VC++ 2005. cannam@86: cannam@86: Prerequisite: you must have the Ogg libraries installed as described cannam@86: later. cannam@86: cannam@86: Prerequisite: you must have nasm installed, and nasmw.exe must be in cannam@86: your PATH, or the path to nasmw.exe must be added to the list of cannam@86: directories for executable files in the MSVC global options. cannam@86: cannam@86: MSVC6: cannam@86: To build everything, run Developer Studio, do File|Open Workspace, cannam@86: and open FLAC.dsw. Select "Build | Set active configuration..." cannam@86: from the menu, then in the dialog, select "All - Win32 Release" (or cannam@86: Debug if you prefer). Click "Ok" then hit F7 to build. cannam@86: cannam@86: VC++ 2005: cannam@86: To build everything, run Visual Studio, do File|Open and open FLAC.sln. cannam@86: From the dropdown in the toolbar, select "Release" instead of "Debug", cannam@86: then hit F7 to build. cannam@86: cannam@86: Either way, this will build all libraries both statically (e.g. cannam@86: obj\release\lib\libFLAC_static.lib) and as DLLs (e.g. cannam@86: obj\release\lib\libFLAC.dll), and it will build all binaries, statically cannam@86: linked (e.g. obj\release\bin\flac.exe). cannam@86: cannam@86: Everything will end up in the "obj" directory. DLLs and .exe files cannam@86: are all that are needed and can be copied to an installation area and cannam@86: added to the PATH. The plugins have to be copied to their appropriate cannam@86: place in the player area. For Winamp2 this is \Plugins. cannam@86: cannam@86: By default the code is configured with Ogg support. Before building FLAC cannam@86: you will need to get the Ogg source distribution cannam@86: (see http://xiph.org/ogg/vorbis/download/), build ogg_static.lib (load and cannam@86: build win32\ogg_static.dsp), copy ogg_static.lib into FLAC's cannam@86: 'obj\release\lib' directory, and copy the entire include\ogg tree into cannam@86: FLAC's 'include' directory (so that there is an 'ogg' directory in FLAC's cannam@86: 'include' directory with the files ogg.h, os_types.h and config_types.h). cannam@86: cannam@86: If you want to build without Ogg support, instead edit all .dsp or cannam@86: .vcproj files and remove any occurrences of "/D FLAC__HAS_OGG". cannam@86: cannam@86: cannam@86: =============================================================================== cannam@86: Building on Mac OS X cannam@86: =============================================================================== cannam@86: cannam@86: If you have Fink or a recent version of OS X with the proper autotooles, cannam@86: the GNU flow above should work. The Project Builder project has been cannam@86: deprecated but we are working on replacing it with an Xcode equivalent.