| MP4v2 1.9.1 Building the Repository |
| *********************************** |
| |
| Table of Contents |
| ***************** |
| |
| 1 Overview |
| 2 Introduction |
| 3 Quickstart |
| 4 Build Process |
| 4.1 Checkout Sources |
| 4.2 Boostrap (Autotools) |
| 4.3 Configure |
| 4.4 Build |
| 4.5 Install |
| 4.6 Create Distribution |
| 4.7 Build Documentation |
| 4.8 Post Site and API Documentation to project website. |
| 5 Platform Notes |
| 5.1 Mac OS X |
| 5.1.1 Default Binaries |
| 5.1.2 Release Binaries |
| 5.1.3 Developer Binaries |
| 5.1.4 Universal Binaries - all architectures |
| 5.1.5 Universal Binaries - selected architectures |
| 5.2 Linux |
| 5.2.1 Default Binaries |
| 5.2.2 Release Binaries |
| 5.2.3 Developer Binaries |
| 5.2.4 Bi-arch compilation |
| 5.3 FreeBSD |
| 5.3.1 Default Binaries |
| 5.3.2 Release Binaries |
| 5.3.3 Developer Binaries |
| 5.3.4 Bi-arch compilation |
| 5.4 Solaris |
| 5.4.1 Default Binaries |
| 5.4.2 Release Binaries |
| 5.4.3 Developer Binaries |
| 5.4.4 Bi-arch compilation |
| 5.5 Cygwin |
| 5.5.1 Default Binaries |
| 5.5.2 Release Binaries |
| 5.5.3 Developer Binaries |
| 5.6 Windows |
| |
| |
| 1 Overview |
| ********** |
| |
| The documented and supported method to build MP4v2 uses the GNU build |
| system (also known as the Autotools). You must first obtain the sources |
| by either downloading and extracting the source-distribution bundle or |
| working directly MP4v2's Subversion repository. We have build documents |
| for both methods, but unless you are a member of the MP4v2 project, you |
| are strongly encouraged to use the source-distribution method. |
| |
| On other supported platforms which lack Autotools we provide an |
| alternative method for building the software. Please see the |
| appropriate platform section. |
| |
| 2 Introduction |
| ************** |
| |
| This document describes the recommended process to build MP4v2 from the |
| repository. This process is a superset of the process to build from a |
| source-distribution bundle. If you are interested in building from a |
| source-distribution bundle then this document is not for you. |
| |
| 3 Quickstart |
| ************ |
| |
| This chapter is for the impatient or those just looking for a quick |
| summary of all the commands used in a typical build. You may skip this |
| summary and jump to *note Build Process::. |
| |
| svn checkout https://mp4v2.googlecode.com/svn/releases/1.9.1 mp4v2 |
| cd mp4v2 |
| autoreconf -fiv |
| rm -fr build/ |
| mkdir build/ |
| cd build/ |
| ../configure |
| make |
| make install |
| make install-man |
| make dist |
| |
| 4 Build Process |
| *************** |
| |
| 4.1 Checkout Sources |
| ==================== |
| |
| Checkout sources from the project's Subversion repository. |
| |
| Sources are checked out from either the trunk, release or a branch. |
| This document was generated from one of those, and for example |
| purposes, we will use exactly the same URL which used to create the |
| distribution which contains this document. |
| |
| If you are a project member, then you may add the appropriate |
| login/password information as needed. |
| |
| svn checkout https://mp4v2.googlecode.com/svn/releases/1.9.1 mp4v2 |
| cd mp4v2 |
| |
| It is recommended to use Subversion 1.5.0 or higher. Lower versions |
| might work. |
| |
| 4.2 Boostrap (Autotools) |
| ======================== |
| |
| The following command causes forces Autotools to regenerate all files |
| and install helper scripts needed at configure-time and to regenerate |
| all files. |
| |
| autoreconf -fiv |
| |
| If you are a project member and preparing for a release, it is |
| important to note that the versions of Autotools available in your path |
| will directly effect files added to the bundle. At the time of writing, |
| the following versions of Autotools are recommended; in some cases a |
| minimum is hard-coded and warnings will be issued if in violation: |
| |
| * GNU autoconf 2.61 or higher (lower versions might work) |
| |
| * GNU automake 1.10 or higher (lower versions might work) |
| |
| * GNU libtool 1.5.26 or higher (lower versions might work) |
| |
| 4.3 Configure |
| ============= |
| |
| The following command configures the project for a build. It is highly |
| recommended that you invoke configure from an empty directory. |
| |
| rm -fr build/ |
| mkdir build/ |
| cd build/ |
| ../configure |
| |
| Please see `INSTALL' for details on configure usage, and standard |
| options. Additionally, the following custom options have been added to |
| `configure': |
| |
| `--disable-debug' |
| Do not generate debug information. Do not direct compiler to |
| generate debugging information. By default the compiler will |
| generate debug information if the platform supports it. |
| |
| `--disable-optimize' |
| Do not optimize. Do not direct compiler to optimize code. By |
| default compiler optimization is enabled if the platform supports |
| it. |
| |
| `--disable-fvisibility' |
| Do not set default ELF symbol visibility. By default configure |
| attempts to detect if the compiler supports this feature. However |
| on some platforms detecting incompatibilty of this feature might |
| not be accurate in which case this option should be given. |
| |
| `--disable-gch' |
| By default certain platforms are marked to use GCC precompiled |
| headers. Generally this greatly decrease build times but may |
| require more diligence for iterative development; that is to say |
| dependencies may not properly be tracked and more frequent `make |
| clean' may be required when headers are changed. Use this option |
| to disable GCC precompiled headers. |
| |
| `--disable-largefile' |
| On some 32-bit platforms or configurations it might be desirable |
| to build without largefile (LFS) support. By default configure |
| attempts to detect formal LFS support and enables it if found. |
| |
| `--disable-util' |
| Do not build/install utilities. This is convenience option for |
| users who desire to skip building the utilities (eg. command-line |
| executables) which are enabled by default. |
| |
| `--enable-bi=ARCH' |
| On bi-arch capable platforms it is possible to generate 32 or 64 |
| bit code. This is supported by adding arguments `-m32' or `-m64', |
| respectively, when compiling or linking. Use this option to |
| override the platform-specific default. |
| |
| `--enable-ub[=ARCHS]' |
| On OSX systems it is possible to generate universal binaries. This |
| is supported by adding one or more argument patterns `-arch ARCH' |
| when compiling or linking. Use this option to either target an |
| architecture different from the platform default, or to produce |
| universal binaries. |
| |
| `--enable-dependency-tracking' |
| Enable automatic dependency tracking for include-files. By default |
| this feature is disabled. |
| |
| |
| 4.4 Build |
| ========= |
| |
| The following command will build MP4v2. |
| |
| make |
| |
| On some platforms `make' refers to a BSD-flavor of make which is not |
| compatible with this project. Check if `gmake' is installed, and if it |
| is, substitute `gmake' wherever you may see `make' in this document. |
| Otherwise you will need to install GNU make package version 3.81 or |
| higher. Lower versions might work. |
| |
| 4.5 Install |
| =========== |
| |
| The following command will install MP4v2. |
| |
| make install |
| make install-man |
| |
| 4.6 Create Distribution |
| ======================= |
| |
| The following command will create a MP4v2 source distribution. It is |
| during this step that shipped documentation is generated. |
| |
| make dist |
| |
| This step in the build process introduces additional requirements to |
| the host system. While most of the following utilities are generally |
| available, `help2man' is used to generate man-pages; however if this |
| command is not available the man-pages will be empty. This is |
| acceptable for non-release builds but for full quality builds this |
| command is required. |
| |
| * GNU help2man 1.36 or higher (lower versions should work) |
| |
| * GNU tar 1.15.1 or higher (lower versions should work) |
| |
| * GNU gzip 1.3.10 or higher (lower versions should work) |
| |
| * bzip2 1.0.4 or higher (lower versions should work) |
| |
| * Info-ZIP zip 2.32 or higher (lower versions should work) |
| |
| 4.7 Build Documentation |
| ======================= |
| |
| This step in the build process introduces some significant requirements |
| to the host system: |
| |
| * GNU texinfo 4.8 or higher (lower versions should work) |
| |
| * Doxygen 1.5.7 or higher (lower versions should work) |
| |
| Documentation that is shipped with source-distribution is generated as |
| part of the *note Build Process:: step. This section documents builds |
| all of the supported methods to build documentation. There are three |
| kinds of documentation in this project; man-pages, articles and API. |
| Documentation must be build from the repository. |
| |
| Man-pages are automatically generated for command-line utilities by |
| using `html2man' which invokes standard options `--help' and |
| `--version' and gleans the information, generating a man-page in nroff |
| script. Note that the utilities will first be built as they are |
| depdendencies of man-page generation. |
| |
| Artcles are usually hand-written and authored in Texinfo format which |
| permits macro-expansions, simple formatting and conversion to several |
| popular formats using the GNU `makeinfo'. A Texinfo manual |
| (http://www.gnu.org/software/texinfo) is available. |
| |
| API is documented inline to C and C++ source files, usually headers |
| using Doxygen comment-formatting. Doxygen is then used to post-process |
| these files and generate documentation in various formats. A Doxygen |
| manual is available at it's main site (http://www.doxygen.org) . |
| |
| The project's goal is to document as thoroughly as possible the public |
| API in MP4v2. Since we never have enough time to document everything, |
| we try to set some priorities in this regard. Generally the public API |
| is the highest priority to document. Next most important is probably |
| underlying utility code which is shared by many developers; for example |
| libplatform. |
| |
| If you need examples of how to document C-compatible source see |
| `include/mp4v2/mp4v2.h' and for C++-only source see |
| `libplatform/io/File.h' . |
| |
| The following table describes the various make targets available for |
| building docs. Note you must first have completed the *note Configure:: |
| step. |
| |
| `make man' |
| Generate man-pages for command-line utilities. |
| |
| `make html' |
| Generate articles in HTML format from `texi' files. |
| |
| `make txt' |
| Generate articles in plaintext format from `texi' files. |
| |
| `make wiki' |
| Generate articles in Google Code Wiki format from `texi' files. |
| |
| `make xml' |
| Generate articles in (Texinfo) XML format from `texi' files. |
| |
| `make api' |
| Generate API in HTML format from header files. |
| |
| `make articles' |
| Convenience; the equivalent of `make html txt wiki xml' . |
| |
| `make doc' |
| Convenience; the equivalent of `make man articles api' . |
| |
| |
| And finally all of the document targets have a corresponding clean |
| target which cleans up generated files. Simply prefix as follows: |
| |
| make manclean |
| make htmlclean |
| make txtclean |
| make wikiclean |
| make xmlclean |
| make apiclean |
| make articlesclean |
| make docclean |
| |
| 4.8 Post Site and API Documentation to project website. |
| ======================================================= |
| |
| This step is for project maintainers and can be used to update Site and |
| API documentation. The following components are updated: |
| |
| * Featured Wiki article: BuildRepository |
| |
| * Featured Wiki article: BuildSource |
| |
| * MP4v2 (trunk) docs (includes Release Notes and other articles, and |
| API docs). |
| |
| This procedure may only be run from a *nix platform and has only been |
| tested on Mac OS X. |
| |
| `make google.clean' |
| Clean any local working copy of google changeset. |
| |
| `make google.post' |
| Generate required docs, sparse-checkout google tree, remove files |
| which are no longer generated, add new files which are generated, |
| and update existing files. |
| |
| `svn ci -m "-refreshed GoogleCode site+api docs." google/.' |
| Check-in changes. This might take several minutes, especially if |
| your upstream bandwidth is limited. |
| |
| |
| 5 Platform Notes |
| **************** |
| |
| MP4v2 builds on many unix-style platforms, also commonly referred to as |
| posix-style systems. Building on Mac OS X, Linux, FreeBSD, Solaris, |
| Cygwin, Windows are known to work. |
| |
| Similar platforms should also work. Please see the following platform |
| specific notes for instructions on commonly used options for various |
| platforms. |
| |
| 5.1 Mac OS X |
| ============ |
| |
| Building on Mac OS X is well supported as it is used by maintainers of |
| this project. The following are the recommended specifications for this |
| platform; but is not necessarily the only configuration that is |
| possible: |
| |
| * Mac Intel hardware |
| |
| * Mac OS X 10.5.7 |
| |
| * Xcode-3.1.2 |
| |
| * gcc 4.0.1 (Apple Inc. build 5493) |
| |
| * gcc 4.2.1 (Apple Inc. build 5570) |
| |
| Note: It is recommended to use the platform distribution's bundled |
| compiler for maximum C++ compatibility. If you build with a custom |
| compiler it will likely introduce non-standard runtime |
| requirements for your users. There are of course many valid |
| reasons to build with unbundled compilers, but be aware that is |
| generally unsupported and left as an exercise to the reader. |
| |
| 5.1.1 Default Binaries |
| ---------------------- |
| |
| The preferred method to produce default binaries is to run configure |
| without any options which will compile with debug+optimize and produce |
| static+shared libraries and dynamic executables. |
| |
| ../configure |
| |
| 5.1.2 Release Binaries |
| ---------------------- |
| |
| The preferred method to produce binaries suitable for releases, (ie. |
| which does not contain debug information) is to pass the following to |
| configure: |
| |
| ../configure --disable-debug |
| |
| 5.1.3 Developer Binaries |
| ------------------------ |
| |
| The preferred method to produce binaries suitable for development is to |
| pass the following to configure. Default Binaries will work, however |
| for the best debugging experience we recommend no optimize and no |
| static libraries. |
| |
| ../configure --disable-optimize --disable-static |
| |
| 5.1.4 Universal Binaries - all architectures |
| -------------------------------------------- |
| |
| The preferred method to produce universal binaries for all supported |
| architectures is to pass the following option to configure. As of this |
| writing, architectures { i386, x86_64, ppc, ppc64 } are built. |
| |
| ../configure --enable-ub |
| |
| 5.1.5 Universal Binaries - selected architectures |
| ------------------------------------------------- |
| |
| The preferred method to produce universal binaries for selected |
| architectures is to specify a comma-delimited list specifying the |
| desired architecture identifiers. Passing the following option will |
| produce universal binaries for architectures { i386, x86_64 }. |
| |
| ../configure --enable-ub=i386,x86_64 |
| |
| 5.2 Linux |
| ========= |
| |
| Building on Linux is well supported as it is used by maintainers of |
| this project. The following are the recommended specifications for this |
| platform; but is not necessarily the only configuration that is |
| possible: |
| |
| * Intel 32-bit or 64-bit hardware |
| |
| * Fedora 10, gcc 4.3.2 |
| |
| * gcc 3.4.0 or higher is reported to work |
| |
| Note: It is recommended to use the platform distribution's bundled |
| compiler for maximum C++ compatibility. If you build with a custom |
| compiler it will likely introduce non-standard runtime |
| requirements for your users. There are of course many valid |
| reasons to build with unbundled compilers, but be aware that is |
| generally unsupported and left as an exercise to the reader. |
| |
| 5.2.1 Default Binaries |
| ---------------------- |
| |
| The preferred method to produce default binaries is to run configure |
| without any options which will compile with debug+optimize and produce |
| static+shared libraries and dynamic executables. |
| |
| ../configure |
| |
| 5.2.2 Release Binaries |
| ---------------------- |
| |
| The preferred method to produce binaries suitable for releases, (ie. |
| which does not contain debug information) is to pass the following to |
| configure: |
| |
| ../configure --disable-debug |
| |
| 5.2.3 Developer Binaries |
| ------------------------ |
| |
| The preferred method to produce binaries suitable for development is to |
| pass the following to configure. Default Binaries will work, however |
| for the best debugging experience we recommend no optimize and no |
| static libraries. |
| |
| ../configure --disable-optimize --disable-static |
| |
| 5.2.4 Bi-arch compilation |
| ------------------------- |
| |
| The preferred method to produce a bi-arch binary is to specify the |
| target (eg. 32-bit) with the following option to configure. This |
| example will produce a 32-bit binary if compiling on a platform which |
| defaults to producing 64-bit binaries. The inverse is also possible. |
| |
| ../configure --enable-bi=32 |
| |
| Warning: Currently bi-arch cross-compilation is not supported due |
| to a bug with libtool which fails miserably during linking. |
| |
| 5.3 FreeBSD |
| =========== |
| |
| Building on FreeBSD is supported. The following are the recommended |
| specifications for this platform; but is not necessarily the only |
| configuration that is possible: |
| |
| * Intel 32-bit or 64-bit hardware |
| |
| * FreeBSD 7.0 Release, gcc 4.2.1 |
| |
| * gcc 3.4.0 or higher is reported to work |
| |
| Note: It is recommended to use the platform distribution's bundled |
| compiler for maximum C++ compatibility. If you build with a custom |
| compiler it will likely introduce non-standard runtime |
| requirements for your users. There are of course many valid |
| reasons to build with unbundled compilers, but be aware that is |
| generally unsupported and left as an exercise to the reader. |
| |
| 5.3.1 Default Binaries |
| ---------------------- |
| |
| The preferred method to produce default binaries is to run configure |
| without any options which will compile with debug+optimize and produce |
| static+shared libraries and dynamic executables. |
| |
| ../configure |
| |
| 5.3.2 Release Binaries |
| ---------------------- |
| |
| The preferred method to produce binaries suitable for releases, (ie. |
| which does not contain debug information) is to pass the following to |
| configure: |
| |
| ../configure --disable-debug |
| |
| 5.3.3 Developer Binaries |
| ------------------------ |
| |
| The preferred method to produce binaries suitable for development is to |
| pass the following to configure. Default Binaries will work, however |
| for the best debugging experience we recommend no optimize and no |
| static libraries. |
| |
| ../configure --disable-optimize --disable-static |
| |
| 5.3.4 Bi-arch compilation |
| ------------------------- |
| |
| The preferred method to produce a bi-arch binary is to specify the |
| target (eg. 32-bit) with the following option to configure. This |
| example will produce a 32-bit binary if compiling on a platform which |
| defaults to producing 64-bit binaries. The inverse is also possible. |
| |
| ../configure --enable-bi=32 |
| |
| Warning: Currently bi-arch cross-compilation is not supported due |
| to a bug with libtool which fails miserably during linking. |
| |
| 5.4 Solaris |
| =========== |
| |
| Building on Solaris is supported. The following are the recommended |
| specifications for this platform; but is not necessarily the only |
| configuration that is possible: |
| |
| * Intel 32-bit or 64-bit hardware |
| |
| * Solaris 10u6, gcc 3.4.3 |
| |
| * gcc 3.4.0 or higher is reported to work |
| |
| Note: It is recommended to use the platform distribution's bundled |
| compiler for maximum C++ compatibility. If you build with a custom |
| compiler it will likely introduce non-standard runtime |
| requirements for your users. There are of course many valid |
| reasons to build with unbundled compilers, but be aware that is |
| generally unsupported and left as an exercise to the reader. |
| |
| Note: Solaris does not (yet) really bundle a compiler. The |
| recommendation is to use the companion-disk compiler for maximum |
| C++ runtime compatibility. It is usually found in `/usr/sfw/bin'. |
| |
| 5.4.1 Default Binaries |
| ---------------------- |
| |
| The preferred method to produce default binaries is to run configure |
| without any options which will compile with debug+optimize and produce |
| static+shared libraries and dynamic executables. |
| |
| ../configure |
| |
| 5.4.2 Release Binaries |
| ---------------------- |
| |
| The preferred method to produce binaries suitable for releases, (ie. |
| which does not contain debug information) is to pass the following to |
| configure: |
| |
| ../configure --disable-debug |
| |
| 5.4.3 Developer Binaries |
| ------------------------ |
| |
| The preferred method to produce binaries suitable for development is to |
| pass the following to configure. Default Binaries will work, however |
| for the best debugging experience we recommend no optimize and no |
| static libraries. |
| |
| ../configure --disable-optimize --disable-static |
| |
| 5.4.4 Bi-arch compilation |
| ------------------------- |
| |
| The preferred method to produce a bi-arch binary is to specify the |
| target (eg. 32-bit) with the following option to configure. This |
| example will produce a 32-bit binary if compiling on a platform which |
| defaults to producing 64-bit binaries. The inverse is also possible. |
| |
| ../configure --enable-bi=32 |
| |
| Warning: Currently bi-arch cross-compilation is not supported due |
| to a bug with libtool which fails miserably during linking. |
| |
| 5.5 Cygwin |
| ========== |
| |
| Building on Cygwin is supported. The following are the recommended |
| specifications for this platform; but is not necessarily the only |
| configuration that is possible: |
| |
| * Intel 32-bit or 64-bit hardware |
| |
| * Cygwin, gcc 4.3.2 |
| |
| * gcc 3.4.0 or higher is reported to work |
| |
| Note: As of this writing, Cygwin has available to it several |
| versions of gcc; only one of which may be found and used in the |
| path as `gcc' and `g++'. Configure will thus find what is probably |
| the older more stable version of gcc in a typical Cygwin |
| environment. If you desire to build with the newer gcc, it is |
| found in the path as `gcc-4' and `g++-4' respectively and you must |
| indicate to configure the desired versions. Defining the following |
| variables beforing running configure should do the trick: |
| |
| setenv CC gcc-4 |
| setenv CXX gcc-4 |
| ../configure |
| |
| 5.5.1 Default Binaries |
| ---------------------- |
| |
| The preferred method to produce default binaries is to run configure |
| without any options which will compile with debug+optimize and produce |
| static+shared libraries and dynamic executables. |
| |
| ../configure |
| |
| 5.5.2 Release Binaries |
| ---------------------- |
| |
| The preferred method to produce binaries suitable for releases, (ie. |
| which does not contain debug information) is to pass the following to |
| configure: |
| |
| ../configure --disable-debug |
| |
| 5.5.3 Developer Binaries |
| ------------------------ |
| |
| The preferred method to produce binaries suitable for development is to |
| pass the following to configure. Default Binaries will work, however |
| for the best debugging experience we recommend no optimize and no |
| static libraries. |
| |
| ../configure --disable-optimize --disable-static |
| |
| 5.6 Windows |
| =========== |
| |
| Native builds on Windows is supported via Microsoft's Visual Studio |
| package. Both the commercial version and free version (express) are |
| known to work. The following are the recommended specifications for |
| this platform; but is not necessarily the only configuration that is |
| possible: |
| |
| * Intel 32-bit or 64-bit hardware |
| |
| * Windows 2000 or higher, Visual Studio 9.0 (aka. Visual Studio 2008) |
| |
| * Visual Studio 9.0 Express is reported to work |
| |
| Only 32-bit binaries are targeted, and win32-API is set to Windows 2000 |
| or higher. Older versions of Windows, or win32-API are not supported. |
| |
| MP4v2 has directory `vstudio9.0/' which contains the necessary |
| solution+project files to produce a basic build of libmp4v2's DLL and |
| several command-line executables. Enabling things such as debugging, |
| optimization, etc, are all left as an exercise to the user. |
| |
| Warning: Project meta-data is stored in header `project.h'. A |
| proper source distribution is built using autotools and generates |
| `TOP/include/mp4v2/project.h' correctly, which is then bundled |
| with our source distribution. This is adequate for building on the |
| Windows platform. |
| |
| However, if you are building from the repository, be warned that |
| there is no method to automatically generate `project.h' on |
| Windows. Instead, we periodically checkin a copy of this file |
| (generated using autotools) as |
| `vstudio9.0/include/mp4v2/project.h' which may from time to time |
| get out of date. If it is significantly out of date, you should |
| find the latest source distribution and copy the `project.h' from |
| there. |
| |
