From aa97e4d4981d61808a558c5ab36be6d3bcc2c4f6 Mon Sep 17 00:00:00 2001 From: Dave Chapman Date: Wed, 16 Feb 2005 19:33:19 +0000 Subject: Initial import of libFLAC from flac-1.1.2.tar.gz git-svn-id: svn://svn.rockbox.org/rockbox/trunk@5983 a1c6a512-1295-4272-9138-f99709370657 --- apps/codecs/libFLAC/README | 257 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 257 insertions(+) create mode 100644 apps/codecs/libFLAC/README (limited to 'apps/codecs/libFLAC/README') diff --git a/apps/codecs/libFLAC/README b/apps/codecs/libFLAC/README new file mode 100644 index 0000000000..e135601037 --- /dev/null +++ b/apps/codecs/libFLAC/README @@ -0,0 +1,257 @@ +/* FLAC - Free Lossless Audio Codec + * Copyright (C) 2001,2002,2003,2004,2005 Josh Coalson + * + * 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. + * + * 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 comprised of + * `libFLAC', a library which implements reference encoders and + decoders, 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 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.2 - 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/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 + 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 check && make install + +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 +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': + +--enable-debug : Builds everything with debug symbols and some +extra (and more verbose) error checking. + +--disable-asm-optimizations : Disables the compilation of the +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. + +--enable-sse : If you are building for an x86 CPU that supports +SSE instructions, you can enable some of the faster routines +if your operating system also supports SSE instructions. flac +can tell if the CPU supports the instructions but currently has +no way to test if the OS does, so if it does, you must pass +this argument to configure to use the SSE routines. If flac +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-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. + +From the top level just 'make -f Makefile.lite'. You can +specify zero or one optional target from 'release', 'debug', +'test', or 'clean'. The default is 'release'. There is no +'install' target but everything you need will end up in the +obj/ directory. + +If you are not on an x86 system or you don't have nasm, you +may have to change the DEFINES in src/libFLAC/Makefile.lite. If +you don't have nasm, remove -DFLAC__HAS_NASM. If your target is +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. + +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 \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, +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. + +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). -- cgit v1.2.3