X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=README;h=7eaec95ef46da18ac2dba0ebec0a693c8d5541ba;hb=c7957b2b54350b60fdeb6c5201bf45e42655cf4b;hp=6df5c7c74cd15c33fed7548a8601297b899dfc04;hpb=f2be7c3213a5de90159f27b9cae57068eb898b08;p=platform%2Fupstream%2Fflac.git diff --git a/README b/README index 6df5c7c..7eaec95 100644 --- a/README +++ b/README @@ -1,73 +1,72 @@ /* 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 + * `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 +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-beta1 - 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 include/ public include files for libFLAC and libFLAC++ man/ the man page for `flac' src/ the source code and private headers @@ -75,6 +74,53 @@ A brief description of the directory tree: =============================================================================== +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 +132,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 +152,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 @@ -114,21 +164,17 @@ 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= --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. @@ -158,108 +204,46 @@ 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 +VC++ 2005: +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 hit F7 to build. - 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 \Plugins -and for Winamp3 this is \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.