octaPNG/INSTALL.md

Compiling octaPNG from source

octaPNG is written to be as portable as possible in order to compile on any system with minimal dependencies, using only one Makefile that accepts command line options. Compilation will yield a single statically-linked binary that can be moved and used from anywhere.

Dependencies

• GCC
• Make
• libpng
• zlib
• pkg-config (optional)

Compiling under Linux and *BSD

These steps are for compiling under Linux, *BSD, or any POSIX-compliant OS using Make.

1. Install gcc, make, pkg-config, and the development libraries for libpng and zlib from your package manager. For example on Ubuntu you can install them using this command:

   sudo apt install build-essential libpng-dev zlib1g-dev pkg-config
   

2. Open a terminal window in the octaPNG source directory (e.g. octapng-master ).

3. Run

   make
   

   or if compiling without pkg-config run

   make nopc
   

4. To install octaPNG (to default prefix /usr/local ) run:

   make install
   

Compiling under Windows

Online

These steps are for compiling under a supported version of Windows with internet access using MSYS2 and MinGW-w64.

1. Install MSYS2. You should now have the directory C:\msys64

2. Run the MSYS2 shell at C:\msys64\msys2_shell.bat and a terminal window will open.

3. Run

   pacman -Syuu
   

   to install any available MSYS2 updates. Repeat this step until there are no more updates.

4. Run

   pacman -S \
   mingw64/mingw-w64-x86_64-gcc \
   mingw64/mingw-w64-x86_64-make \
   mingw64/mingw-w64-x86_64-libpng \
   mingw64/mingw-w64-x86_64-zlib \
   mingw64/mingw-w64-x86_64-pkg-config
   

   to install all dependencies.

5. Place the octaPNG source directory into C:\msys64\home\USERNAME where USERNAME is your Windows user name. You should now have the directory C:\msys64\home\USERNAME\octapng-master or similar.

6. Close the MSYS2 shell, run the MinGW shell at C:\msys64\mingw64.exe or C:\msys64\mingw64_shell.bat and a terminal window will open.

7. Run

   cd octapng-master
   mingw32-make
   

   If that doesn't work, run

   mingw32-make CCPRFX="x86_64-w64-mingw32-"
   

Offline

These steps are essentially the same as those for online compilation except they'll work for any Windows version without internet access, by downloading all the necessary files beforehand. If online compilation didn't work try offline compilation.

1. Download the MSYS2 installer [32-bit / 64-bit], the MinGW-w64 archive [32-bit / 64-bit], the pre-built libpng [32-bit / 64-bit] and zlib [32-bit / 64-bit] archives, the pkg-config archive [32-bit / 64-bit], and the ZSTD command line tool [32-bit / 64-bit].

2. Install MSYS2. You should now have the directory C:\msys64

3. Extract the MinGW-w64 archive into C:\msys64 . You should now have the directory C:\msys64\mingw64

4. Place the octaPNG source directory, the libpng and zlib archives, the pkg-config archive, and the ZSTD tool renamed as zstd.exe into C:\msys64\home\USERNAME where USERNAME is your Windows user name. You should now have the directory C:\msys64\home\USERNAME\octapng-master or similar.

5. Run the MSYS2 shell at C:\msys64\msys2_shell.bat and a terminal window will open.

6. Run

   ./zstd -d --rm *.zst
   for f in *.tar*; do bsdtar -xvf "$f"; done
   

   and you'll find the directory C:\msys64\home\USERNAME\mingw64 is created.

7. Merge this directory with the one inside C:\msys64

8. Close the MSYS2 shell, run the MinGW shell at C:\msys64\mingw64.exe or C:\msys64\mingw64_shell.bat and a terminal window will open.

9. Run

   cd octapng-master
   mingw32-make
   

   If that doesn't work, run

   mingw32-make CCPRFX="x86_64-w64-mingw32-"
   

32-bit Windows

To compile under a 32-bit version of Windows follow the same steps for online or offline compilation, with the following changes:

• The MSYS2 directory will be C:\msys32

• The MinGW directory will be C:\msys32\mingw32

• The MinGW shell will be named mingw32.exe or mingw32_shell.bat

• The command to install all dependencies using the MSYS2 shell will be

  pacman -S \
  mingw32/mingw-w64-i686-gcc \
  mingw32/mingw-w64-i686-make \
  mingw32/mingw-w64-i686-libpng \
  mingw32/mingw-w64-i686-zlib \
  mingw32/mingw-w64-i686-pkg-config
  

• The compilation command will be

  mingw32-make CCPRFX="i686-w64-mingw32-"
  

Compiling under other systems

Any system containing...

• An ANSI C compiler
• A POSIX-compliant Make tool
• The needed development libraries (preferably with pkg-config)

...should allow compiling the octaPNG source without issue. The Makefile accepts a myriad of command line options that you can use to fine-tune the compilation process, familiarize yourself with them by reading the full option list or the examples below. Avoid editing the Makefile by hand, if your use case isn't covered please report an issue.

Makefile options

The available make command line options are listed at the top of the Makefile exactly as they are on this page, view them anytime using your favorite text editor or run make help from a POSIX shell.

See also the examples below.

--- USAGE

make [OPTIONS] [TARGETS]

--- OPTIONS

builddir=BUILDDIR   Compiled binary path. (default=.)
exename=EXENAME     Compiled binary name. (default=octapng)
exeprfx=EXEPRFX     Compiled binary prefix.
exesufx=EXESUFX     Compiled binary extension.
objsufx=OBJSUFX     Compiled object extension. (default=.o)

prefix=PREFIX       Installation path. (default=/usr/local)
bindir=BINDIR       Installed binary path. (default=PREFIX/bin)
mandir=MANDIR       Installed manuals path. (default=PREFIX/share/man)
man1dir=MAN1DIR     Installed man1 path. (default=MANDIR/man1)

warnings=...        Additional warning flags.
cflags=...          Additional general compiler flags.
ldflags=...         Additional general linker flags.
cflibs=...          Additional library compiler flags.
ldlibs=...          Additional library linker flags.

--- ADVANCED OPTIONS

CC=...              Compiler command. (default=gcc)
CCPRFX=...          Compiler command prefix.

WARNINGS=...        Overwrite warning flags.
CFLAGS=...          Overwrite general compiler flags.
LDFLAGS=...         Overwrite general linker flags.
CFLIBS=...          Overwrite library compiler flags.
LDLIBS=...          Overwrite library linker flags.

CFLIBS_NOPC=...     Overwrite library compiler flags for
                    targets `nopc` and `nopc_basic`.
LDLIBS_NOPC=...     Overwrite library linker flags for
                    targets `nopc` and `nopc_basic`.

--- TARGETS

all                 Compile program. (default)
nopc                Compile program without `pkg-config`.
nopc_basic          Compile program without `pkg-config` in
                    non-POSIX environments. (ignores BUILDDIR)

clean               Delete compiled program.
install             Install compiled program into PREFIX.
uninstall           Delete installed program from PREFIX.

Examples

# compile program into a `build` directory, then install into prefix `/usr`
make builddir=build
make builddir=build install prefix=/usr

# uninstall program from prefix `/usr`
make uninstall prefix=/usr

# compile on 64-bit Windows using the full MinGW-w64 command prefix, and use
# `.exe` as the binary extension
mingw32-make CCPFX="x86_64-w64-mingw32-" exesufx=".exe"

# compile a dynamically-linked binary with debug symbols and no optimization
make LDFLAGS="" cflags="-g -O0"

# compile without `pkg-config` and specify additional search paths
make nopc cflibs="-I/opt/include -L/opt/lib"

# compile without `pkg-config` or any POSIX tools, manually overwrite search
# paths and library link flags
nmake nopc_basic CFLIBS_NOPC="-Iinclude" LDLIBS_NOPC="libpng16.a zlib.a"

# compile a binary named `foo-octapng-bar` and store name inside binary
make exename="foo-octapng-bar"

# compile a binary named `foo-octapng-bar` but don't store name inside binary
make exeprfx="foo-" exesufx="-bar"