gaspard7/wiki_gpac huggingface dataset:
Developer resources

* current build status of GPAC: <a href="https://buildbot.gpac.io" target="_blank">buildbot.gpac.io</a>
* current test suite status of GPAC: <a href="https://tests.gpac.io" target="_blank">tests.gpac.io</a>
* full API documentation: <a href="https://doxygen.gpac.io/modules.html" target="_blank"> doxygen.gpac.io</a>
* the <a href="https://github.com/gpac/testsuite/tree/master/scripts" target="_blank">testsuite scripts</a> might give you additional info on how to use GPAC tools
* tips and tricks in our [github discussions](https://github.com/gpac/gpac/issues?utf8=%E2%9C%93&q=) and our old [sourceforge forums](https://sourceforge.net/p/gpac/discussion/)

<br/>

!!! note

    The documentation assumes GPAC 2.0 or above. Some informations relative to MP4Box may still be useful for older versions.

.
Build MP4Box with Visual Studio {: data-level="all"}

We published a minimal solution to build MP4Box.exe only, with zero dependency. No DLL to distribute.

You need Visual Studio 2010 or more recent (a pop-up will ask you to upgrade your projects, just accept). Open [build/msvc10/gpac\_mp4box\_mini.sln](https://github.com/gpac/gpac/blob/master/build/msvc10/gpac_mp4box_mini.sln) and build (Debug or Release).

That's all!
Build MP4Box with Make

On your system, you need the following tools installed on your system:

*   git
*   gcc
*   make
*   libpthread-dev (should be available on any development system)

In your favorite terminal, type:

```
git clone https://github.com/gpac/gpac.git
cd gpac
./configure --static-mp4box --use-zlib=no
make -j4
```

_Note_

`--use-zlib` is optional, specify it only if you don't want support for zlib (compressed boxes, compressed files, ...).

To execute MP4Box, assuming you are still in the same directory (i.e. the [root of the GPAC repository](https://github.com/gpac/gpac)), you will find the MP4Box executable at:

```
bin/gcc/MP4Box
```

To install MP4Box on your system:

```
sudo make install
```

### Check installation

now when you type

```
which MP4Box
```

you should see

```
/usr/local/bin/MP4Box
```

which is the default install folder for the version we have just built. You can tweak this with the `-prefix=` configure option.

If you see `/usr/bin/MP4Box` (no "local/" in here), uninstall GPAC from your local packager. On MacOS, go to Finder and unmount the app on the left panel, or uninstall it from your package manager ('port' or 'homebrew' or 'fink').

### Update to a newer revision

Of course you want to keep updated with the latest build without having to download the full repository again or re-execute the configuration when not necessary (it may be necessary sometimes, see below "Clean your build" if things go unexpectedly):

```
cd gpac
git pull
make -j4
sudo make install
```

That's all!

### Clean your build

If things go wrong and you suspect there is an issue in your configuration, the fastest way to restart a clean build is:

```
cd gpac
make distclean
./configure --static-mp4box --use-zlib=no
make -j4
```

### Cross-compilation

Cross-compiling GPAC is quite standard, and requires only a modification at the 'configure' step. Use `--extra-cflags=` and `--extra-ldflags=` to add your environment flags:

```
cd gpac
./configure --target-os=$OS --cross-prefix="$crossPrefix" --extra-cflags="-I$PREFIX/$host/include" --extra-ldflags="-L$PREFIX/$host/lib" --prefix=$PREFIX/$host --static-mp4box --use-zlib=no
make -j4
```

For example, to use the 'x86\_64-w64-mingw32' toolchain to cross-build from Linux to Windows:

```
cd gpac
./configure --target-os=mingw32 --cross-prefix=x86_64-w64-mingw32- --prefix=build/x86_64-w64-mingw32 --static-mp4box --use-zlib=no --extra-cflags="-Ibuild/x86_64-w64-mingw32/include" --extra-ldflags="-Lbuild/x86_64-w64-mingw32/lib"
make -j4
```

You can find more examples in [our TravisCI script](https://github.com/gpac/gpac/blob/master/.travis.yml).
In source tree building {: data-level="all" }

If you build GPAC directly in the source tree (i.e., running `./configure && make` in the same directory as the configure script), the following steps must be done when upgrading your code base to a new version of GPAC, or when switching branches:

- uninstall any previous version of GPAC (optional, the build system as of 1.0 is independent from the presence of any other version of libgpac headers on the system)

`make uninstall`
 
- clean all dependencies and obj files - this will remove any local build files (dep, obj) and configuration file (config.mak, config.log ...) 

`make distclean`

- reconfigure 

`./configure`

- build

`make -j`
Out of source tree building

To avoid the issue of cleaning dependencies, it is safer to have one dedicated build directory for each branch you test:

-  `mkdir bin/master && cd bin/master && ../../configure && make -j`
-  `mkdir bin/somebranch && cd bin/master && git checkout somebranch && ../../configure && make -j`

By doing so, you don't need to cleanup or reconfigure when changing branches:

```
cd bin/master && git checkout master && git pull && make -j
cd bin/somebranch && git checkout somebranch && git pull && make -j
```

You may however need to re-run the configure script in case the build system was modified after a git pull, but this is not very frequent (and usually the build will fail in that case).
Overview {: data-level="all"}

Windows users often ask about how to compile GPAC and generate an installer. The main problem on platforms, like Windows, that don't rely on a modern package system is to get your dependencies with the correct version. Fortunately, we release a package containing most of the extra-libs we use.

The first reaction of unix users when compiling GPAC is to use an existing gnu/gcc compilation chain (Cygwin, MinGW...). However another free solution exists using Microsoft Visual Studio Express Edition. This article gives you some strong clues about the tools you need to recompile binaries and generate an installer using the latter.

**This article was made using a clean install within a virtualized Windows XP. It focuses on command-lines but converting and compiling projects from the GUI works.**
Getting the tools

*   [Download Visual C++ Express](http://www.microsoft.com/express/Downloads/) on the web (2010 has been used for this article).
*   Ensure you have access to msbuild.exe which is provided with [the .NET framework 3.5](http://www.microsoft.com/downloads/en/details.aspx?FamilyId=333325fd-ae52-4e35-b531-508d977d32a6&displaylang=en) (it should be installed on any up-to-date Windows): `%WINDIR%\Microsoft.NET\Framework\v3.5\MSBuild.exe`
From now, I'll assume it is in your path and therefore refer it as MSBuild.exe
*   You'll need to compile assembly code using [NASM](http://www.nasm.us/). Add the binaries' directory to your PATH.
*   SDL (alternative audio/video output for the player) and Gecko (to have the GPAC player as a Firefox plugin) installs need `wget.exe` to download resources from web servers.
*   SDL install needs to unzip a file. Therefore put `unzip.exe` within your PATH to have SDL support.
*   OpenHEVC support requires that you have `git.exe` in your PATH.

*   If you have MFC/AFX support (i.e. Visual C++ with a non-free edition) and wish to have native audio/video outputs using DirectX on your player, you shall install the DirectX SDK from the Microsoft website.
Rem: some users told us June 2010 DirectX SDK got rid of some needed components. February 2010 SDK should work.

Note: if you don't have the MFC/AFX headers, GPAC still provides you with SDL as an audio/video output.
Getting the source code (or organizing it)

Make sure you have git and [subversion installed on your system](http://subversion.apache.org/), and **add the subversion binaries to your path**.

Create a directory that I'll call "root directory" in this article. **All the commands are executed from your root directory.** Open a prompt and then type the following command:

```
> git clone https://github.com/gpac/gpac.git
```

Download the file at <https://download.tsi.telecom-paristech.fr/gpac/gpac_extra_libs.zip>.

Unzip `gpac_extra_libs.zip` so that you have a gpac\_extra\_libs directory containing the files.
Compiling GPAC dependencies (extra libs)

The GPAC extra\_libs package is provided with a Visual Studio 2005 solution, we need to upgrade it (note: if you use the graphical interface, Visual C++ will try to convert it automatically) :

*   If you have a commercial edition of Visual C++:

1.  Find `devenv` within your Visual C++ install directory (should be `%VS90COMNTOOLS%\\..\\IDE\\devenv.exe`)
2.  
```
> msbuild.exe gpac_extra_libs/build/msvc/BuildAll_vc10.sln /t:Build  /p:Configuration=Release /p:Platform=Win32
```
    
For recent versions of Visual Studio (2015+), add `/p:PlatformToolset=v140` to the previous command.

*   If you have a free edition of Visual C++:

1.  Find vcbuild.exe within your Visual C++ install directory (should be `%PROGRAMFILES%\Microsoft Visual Studio 10.0\VC\vcpackages\vcbuild.exe`)
2.  
```
> vcbuild.exe gpac_extra_libs\build\msvc\BuildAll_vc10.sln
  /msbuild:Configuration=Release
  /msbuild:Platform=Win32
```
    

VCbuild actually compiles the solution as it converts it. Sometimes VCbuild tries to build configurations that will fail ("RELEASE|SMARTPHONE 2003 (ARMV4)" for instance) : ignore them.

Check the compilation has succeeded by listing the directory containing the binaries:

```
> dir gpac_extra_libs\lib\win32\release
```
    
You're expected to see .lib and .dll files relative to the extra libs you're interested in (compulsory zlib, then optional js, png, jpeg, faad, mad, freetype, etc.).

Copy the binaries to the right GPAC directories. Execute:


```
> gpac_extra_libs\CopyLibs2Public.bat x86
```
Compiling GPAC

```
> gpac_public\version.bat
> msbuild.exe gpac_public/build/msvc10/gpac.sln /t:Build /p:Configuration=Release /p:Platform=Win32
```
    

If you get a pre-generation error, please check subversion binaries (and especially `svnversion`) are in your PATH.

All projects won't compile on your desktop using this configuration. For instance `Platinum` (UPnP) support is not covered by this article.

If you want to have some audio/video support, make sure you installed the optional packages at the "Getting the tools" step.
Making an installer

GPAC uses [NSIS](http://nsis.sourceforge.net) to generate an installer. The NSIS script is located at `bin\Win32\release\nsis_install\gpac_installer.nsi`.

**The current script won't succeed unless you have successfully compiled everything.**

Therefore you need to modify the script (remove lines relative to the missing binaries). Depending on what you have done, you have two possibilities:

*   launch the script from the `bin\Win32\release\nsis_install` directory to generate an unversionned installer;
*   if you have no local modification on the repository, launch the batch from the GPAC root directory (`gpac_public\generate_installer.bat)` to generate a clean versionned installer of GPAC.
(Re-)Installing

If macports is installed, [uninstall it](http://guide.macports.org/chunked/installing.macports.uninstalling.html):

```

 sudo port -f uninstall installed
sudo rm -rf /opt/local /Applications/DarwinPorts /Applications/MacPorts /Library/LaunchDaemons/org.macports.* /Library/Receipts/DarwinPorts*.pkg /Library/Receipts/MacPorts*.pkg Library/StartupItems/DarwinPortsStartup /Library/Tcl/darwinports1.0 /Library/Tcl/macports1.0 ~/.macports
```
 
[Install macport](http://distfiles.macports.org/MacPorts/). You MUST install a version >=1.9.x
Custom flags for OSX 10.5 and 10.6 compatibility

If you plan to generate GPAC binaries compatible with 10.5, add the following lines at the end of `/opt/local/etc/macports/macports.conf`:

```

macosx_deployment_target 10.4
sdkroot /Developer/SDKs/MacOSX10.5.sdk
```
 
This allows compiling a 10.5 binary with a 10.4 compatible dyld (dyn. loader). Furthermore, you will need to install the 10.5 development SDK. Such binaries should work on any 32 bits x86 versions of OS X.
Custom flags for OSX 10.6 32 bits only

If you are on a 10.6 platform with default targeting to x86\_64 (i.e. x86\_64 compatible cpu, whatever is your kernel configuration), you still may want to generate i386 binaries. Uncomment the `build_arch i386` line of `/opt/local/etc/macports/macports.conf`. Also comment the `universal_archs` feature as MacPorts may end up in an unpredictable state and you won't be able to compile GPAC with most features:

```

build_arch i386
MacPorts packages

To install a package, type:

```

sudo port install my_package_name
```
 
The command-line to install all the packages (compulsory and optional) can be found below in this chapter.

The zlib package is required to build GPAC.

To install all required packages, type:

```

sudo port install pkgconfig freetype libpng jpeg spidermonkey185 libsdl-devel ffmpeg faad2 libmad xvid libogg libvorbis libtheora a52dec openjpeg
``` 

**WARNING:** it is possible that some ports are not working for your system. In this case, you should get  the latest version of the source code of the package, and recompile it locally.

If you have configured macports to generate binaries compatible with 10.5, you must edit `/opt/local/bin/sdl-config` and replace the line below ` --cflags` with the following:
 `echo -I${prefix}/include/SDL -D_THREAD_SAFE -arch i386` 
If you want to cross-compile from a 64 bits environment to a 32 bits target, you may encounter [this bug](https://trac.macports.org/ticket/28935) with the ffmpeg package (old versions), or [this bug](https://trac.macports.org/ticket/30137) with newer ffmpeg versions.
_Deprecated_ Setting up UPnP (Optional)

Install [Java developer package](http://developer.apple.com/java/download/) if your OSX version is > 10.6.3.

Install the Scons build system:
 `sudo port install scons` 

Get the platinum source code patched for gpac here: gpac.sourceforge.net/downloads/platinum\_sdk\_0.4.5.zip, and extract it.
Edit file `Platinum/Platinum/Build/Targets/universal-apple-macosx/Config.scons` as follows:

If building for 10.6 64bits, keep the following flags:

```

universal_flags = [('-arch', 'x86_64'), ('-isysroot', '/Developer/SDKs/MacOSX10.6.sdk'), '-mmacosx-version-min=10.6']
``` 

Otherwise, set the flags to:

```

universal_flags = [('-arch', 'i386'), ('-isysroot', '/Developer/SDKs/MacOSX10.5.sdk'), '-mmacosx-version-min=10.5']
``` 
 
Depending on your GCC version, you may need to edit the file `Platinum/Platinum/Build/Boot.scons` and replace the line

```

BoolVariable?('stop_on_warning', 'Stop the build on warnings', True),
```
 
with the following:

```

BoolVariable?('stop_on_warning', 'Stop the build on warnings', False),
``` 

then go to `Platinum/Platinum` and type:

```

scons
cp Build/Targets/universal-apple-macosx/Debug/*.a gpac/extra_lib/lib/gcc
```
Setting up OpenSVCDecoder (Optional)

Get the latest GPAC [extra libs package](http://gpac.svn.sourceforge.net/viewvc/gpac/trunk/gpac_extra_libs/gpac_extra_libs.zip).

Unzip and go to `./opensvcdecoder`. Build using

```

cmake .
```

then copy the library to `/opt/local/lib` (or any place included in your link settings):
```

sudo cp ./CommonFiles/src/libOpenSVCDec.dylib /opt/local/lib
```

The OpenSVCDecoder in gpac\_extra\_libs package is version 1.11 (latest) patched for MSVC and OS X compilation.
Configure gpac

If you plan to generate GPAC binaries compatible with 10.5, type the following configure:

```

./configure --extra-cflags="-arch i386 -isysroot /Developer/SDKs/MacOSX10.5.sdk" --extra-ldflags="-mmacosx-version-min=10.4 -arch i386 -isysroot /Developer/SDKs/MacOSX10.5.sdk"
```
 
This allows compiling a 10.5 binary with a 10.4 compatible dyld (dynamic loader).

If you don't plan to generate GPAC binaries compatible with 10.5, type the following configure:
 `./configure` 

Build GPAC by typing
 `make` 

If you have setup UPnP, type
 `make -C modules/platinum` 

If you have setup OpenSVC decoder, type
 `make -C modules/opensvc_dec`
Installing gpac

If you want to generate a DMG package for GPAC, regardless of 10.5 compatibility, type
 `./mkdmg` 
or
 `make dmg` 

This will produce a file called `GPAC-$VERSION-r$REVISION.dmg`

If you want to install GPAC directly on your system, type
 `sudo make install` 

**NOTE: DO NOT RUN ./mkdmg AFTER make install, THE BINARIES WON'T BE USEABLE THROUGH THE DMG ARCHIVE. INSTEAD USE make dmg**

Now you deserve a coffee, enjoy it :)
Hacks

From this point on, every command needs to be run in the **`MSYS2 MinGW 64-bit`** terminal (and **not** in the `MSYS2 MSYS` terminal)

For the build scripts to run properly we need some small hacks for commands that don't have the correct name, etc.:

```
cp /mingw64/bin/ar /mingw64/bin/x86_64-w64-mingw32-ar
cp /mingw64/bin/ranlib /mingw64/bin/x86_64-w64-mingw32-ranlib

cat > /mingw64/bin/x86_64-w64-mingw32-windres << 'EOF'
#!/bin/sh
/mingw64/bin/windres "$@"
EOF
```
Get the source

In a common directory, clone the two repositories:

```
git clone https://github.com/gpac/gpac.git
git clone https://github.com/gpac/deps_mingw.git
```

To reiterate, from this point on every command needs to be run in the **`MSYS2 MinGW 64-bit`** terminal (and **not** in the `MSYS2 MSYS` terminal)
Build GPAC

If the dependencies have built successfully, we can now build gpac. 

The following is a configure command that should work in this particular set up and tries to enable the most features, but you can tweak it to suit your needs and the dependencies you have actually built. 

```
gpac $ ./configure  --extra-ldflags=' -static-libstdc++ -static-libgcc ' --disable-lzma --use-zlib=local --sdl-cfg=../deps_mingw/zenbuild/build/release/x86_64-w64-mingw32/bin
```

and then finally: 

```
gpac $ make -j4
```

The binaries will be in `gpac/bin/gcc/`, you can either `make install`, or adjust your `PATH` and `LD_LIBRARY_PATH` variables to use them for there.
Upgrade

```bash
git pull
make
```

If this fails, do ```make clean```.

If this fails again, reconfigure your GPAC with the same option as you previously did: ```./configure --xxx ...```. You can find these options at the top of your config.mak or config.h files (located in the folder where you call the ```configure``` script from).

_If you are upgrading from a previous version (especially going from below 1.0.0 to 1.0.0+) you should run `make uninstall ; make distclean` before running `./configure`._
GPAC easy build (recommended for most users)

Install the development packages for the third-party libraries GPAC is able to leverage: 

```bash
sudo apt install zlib1g-dev libfreetype6-dev libjpeg62-dev libpng-dev libmad0-dev libfaad-dev libogg-dev libvorbis-dev libtheora-dev liba52-0.7.4-dev libavcodec-dev libavformat-dev libavutil-dev libswscale-dev libavdevice-dev libnghttp2-dev libopenjp2-7-dev libcaca-dev libxv-dev x11proto-video-dev libgl1-mesa-dev libglu1-mesa-dev x11proto-gl-dev libxvidcore-dev libssl-dev libjack-jackd2-dev libasound2-dev libpulse-dev libsdl2-dev dvb-apps mesa-utils libcurl4-openssl-dev
```

This list should work on Ubuntu from 14.04 (`trusty`) to at least 22.04 (`jammy`). 

If you use Debian instead of Ubuntu, replace `libjpeg62-dev` with `libjpeg62-turbo-dev`. It should work at least from Debian 9 (`stretch`) to 12 (`bookworm`).

_[Also tested on **archlinux-2022.02.01-x86_64** with the following: `pacman -S zlib freetype2 libjpeg-turbo libpng libmad faad2 libogg libvorbis libtheora a52dec ffmpeg libxv mesa glu xvidcore openssl jack2 alsa-lib libpulse sdl2`]_

Once the packages are installed, you can follow the general build instructions from the previous section.
MP4Box & gpac only (minimal static build)

_This build is intended if you only need GPAC core features such as demuxing, muxing and streaming or if you need a static build._

To build only the MP4Box and gpac command line utilities, you need to: 

0. Install build tools

```bash
sudo apt install build-essential pkg-config git
```

1. Install zlib

```bash
sudo apt install zlib1g-dev
```

2. Get the code

```bash
git clone https://github.com/gpac/gpac.git gpac_public
cd gpac_public
```

3. Build

_If you are upgrading from a previous version (especially going from below 1.0.0 to 1.0.0+) you should run `make uninstall ; make distclean` before running `./configure`._

```bash
./configure --static-bin
make
```

4. Use

You can either:

 -  `sudo make install` to install the binaries,
 - or use the `MP4Box` or `gpac` binary in `gpac_public/bin/gcc/` directly, 
 - or move/copy it somewhere manually.
Building other dependencies

From now on, we'll call the base working directory `<GPAC_ROOT_DIR>`.

1. Get the code

```bash
<GPAC_ROOT_DIR>$ git clone https://github.com/gpac/gpac.git gpac_public

<GPAC_ROOT_DIR>$ git clone https://github.com/gpac/deps_unix
<GPAC_ROOT_DIR>$ cd deps_unix
<GPAC_ROOT_DIR>/deps_unix$ git submodule update --init --recursive --force --checkout
```

The convention of calling the main gpac repository `gpac_public` here is quite important for some scripts. If you don't you'll have to adapt the scripts in `deps_unix`. 

2. Build the dependencies

```bash
<GPAC_ROOT_DIR>/deps_unix$ ./build_all.sh linux
```

If all went well, you should see some libs have been copied over to the gpac repository. It should look something like this: 

```bash
<GPAC_ROOT_DIR>/deps_unix$ ls -l ../gpac_public/extra_lib/lib/gcc/
total 11240
-rw-r--r-- 1 u g   11820 Aug 23 16:31 libArithCoding.a
-rw-r--r-- 1 u g   72260 Aug 23 16:31 libcaption.a
-rw-r--r-- 1 u g  108734 Aug 23 16:31 libDRCdec.a
-rw-r--r-- 1 u g  129430 Aug 23 16:31 libFDK.a
-rw-r--r-- 1 u g  119624 Aug 23 16:31 libFormatConverter.a
-rw-r--r-- 1 u g  298372 Aug 23 16:31 libgVBAPRenderer.a
-rw-r--r-- 1 u g   52192 Aug 23 16:31 libIGFdec.a
-rw-r--r-- 1 u g  230002 Aug 23 16:31 libilo.a
-rw-r--r-- 1 u g 5416016 Aug 23 16:32 libmmtisobmff.a
-rw-r--r-- 1 u g  218566 Aug 23 16:32 libmmtisobmff_c.a
-rw-r--r-- 1 u g  270460 Aug 23 16:31 libMpeghDec.a
-rw-r--r-- 1 u g   22388 Aug 23 16:31 libMpeghUIMan.a
-rw-r--r-- 1 u g   98452 Aug 23 16:31 libMpegTPDec.a
-rw-r--r-- 1 u g 3431798 Aug 23 16:31 libopenhevc.a
-rw-r--r-- 1 u g  888206 Aug 23 16:29 libOpenSVCDec.a
-rw-r--r-- 1 u g   10514 Aug 23 16:31 libPCMutils.a
-rw-r--r-- 1 u g   33888 Aug 23 16:31 libSYS.a
-rw-r--r-- 1 u g   60078 Aug 23 16:31 libUIManager.a
```

(contents and versions may differ depending on updates and deprecated features)
Building GPAC

Now that all the set up is done, we can build gpac by simply doing: 

```bash
<GPAC_ROOT_DIR>/gpac_public$ ./configure
<GPAC_ROOT_DIR>/gpac_public$ make
<GPAC_ROOT_DIR>/gpac_public$ sudo make install
```

_[on Arch Linux, use `./configure --prefix=/usr` since Arch doesn't use /usr/local by default]_

### Upgrading from a previous version

If you already have a gpac version installed, or if you have already built gpac in the same directory, **especially going from a version below 1.0.0 to 1.0.0 and after**, you should run

```bash
<GPAC_ROOT_DIR>/gpac_public$ make uninstall
<GPAC_ROOT_DIR>/gpac_public$ make distclean
```

**before** running `./configure`. 

### Install for developers

If you want to use GPAC for development (in your own code for example), you can use `make install-lib`. 

It will install the necessary libraries and header files. It will also install a `gpac.pc` file for `pkg-config`. With it you can easily build projects that use the gpac library with something like:

```sh
$ gcc -o example $(pkg-config --cflags gpac) example.c $(pkg-config --libs gpac)
```

### Packaging

To generate a .deb package, you can use `make deb`. 

You will probably have to install some packaging tools to run it:

```bash
sudo apt install fakeroot dpkg-dev devscripts debhelper ccache
```