Jpegli Documentation

To help fuzzers detect programming errors (like out-of-bounds access or undefined behavior), use the following assertion macros:

• JPEGLI_DASSERT: Enabled in Debug builds (including ASan, MSan, and UBSan). Use these for general logic checks. Avoid complex checks that run multiple times per pixel to maintain fuzzing performance.
• JPEGLI_CHECK_IMAGE_INITIALIZED(image, rect): Specifically for MSan builds. Use this to explicitly check that a portion of an image is expected to be initialized. This helps catch errors earlier in the decoding/encoding process.

MSYS2 provides different environments targeting different runtimes and compilers. Crucially, all package installations and updates must be performed from within the MSYS environment, not the specific build environment. After installing packages, you must exit all terminals and restart your desired build environment.

• MINGW32: For 32-bit Windows builds. Package prefix: mingw-w64-i686.
• MINGW64: The primary environment for 64-bit Windows using the MSVCRT runtime. Package prefix: mingw-w64-x86_64.
• UCRT64: Uses the Universal C Runtime (UCRT) used by modern Visual Studio. Best for interoperability with Visual Studio projects. Package prefix: mingw-w64-ucrt-x86_64.
• CLANG64: Supports the clang compiler, but gimp packages are not available here. Package prefix: mingw-w64-clang-x86_64.

In MSan builds, using uninitialized memory in a way that affects program flow (e.g., in an if statement or a ternary operator) triggers an error. Simple arithmetic or memcpy over uninitialized memory is generally not an error.

Dealing with SIMD padding

When performing vectorized operations, you often operate over uninitialized padding memory at the end of a row/region. To prevent MSan errors when these values are used in operations like NearestInt(), use the following pattern:

1. Use msan::UnpoisonMemory on the portion of the last SIMD vector being processed.
2. Use msan::PoisonMemory on the corresponding output values after processing.
3. Add a comment explaining why this is safe (e.g., no cross-lane computation is involved).

Note: Do not simply initialize all padding memory in all builds; this can hide logic bugs and incur performance penalties.

To perform a standard release build and execute the project's unit tests, use the release command via the ci.sh script.

By default, build commands like release and opt will automatically run tests. If you wish to build without running tests, set the SKIP_TEST environment variable to 1.

./ci.sh release

To build jpegli on a Debian or Ubuntu-based system, you must install the core build tools and dependencies. Ensure your default clang compiler is at least version 6.

If you have a newer version installed (e.g., clang-7) but the default clang --version reports an older version, use update-alternatives to set the correct default.

Note: This list excludes dependencies already located in the third_party directory.

# Install core dependencies
sudo apt install clang cmake doxygen graphviz ninja-build libpng-dev

# If clang is outdated, update the defaults (example for clang-7)
sudo update-alternatives --install /usr/bin/clang++ clang++ /usr/bin/clang++-7 100
sudo update-alternatives --install /usr/bin/clang clang /usr/bin/clang-7 100

To build Jpegli on macOS, you must first install several dependencies using Homebrew. Note that OSX builds are provided on a "best effort" basis and may have incomplete test coverage or excluded sub-projects.

1. Ensure brew doctor reports no serious problems and that you have an up-to-date version of Xcode installed.
2. Install llvm (this may take several hours).
3. Install the required libraries and build tools.

Note: You must ensure that which clang points to the Homebrew-installed version (/usr/local/opt/llvm/bin/clang) rather than the Xcode default. If it does not, update your PATH environment variable.

brew install llvm
brew install coreutils cmake giflib jpeg-turbo libpng ninja zlib

To build the GIMP plugin for jpegli:

1. Install the relevant gimp package from the MSYS environment (e.g., mingw-w64-x86_64-gimp).
2. If using clang, use ./ci.sh. Otherwise, use cmake within a build directory:

   cd build
   rm -r CM*
   cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo \
      -DBUILD_TESTING=OFF -DBUILD_SHARED_LIBS=OFF \
      -DJPEGLI_ENABLE_BENCHMARK=OFF -DJPEGLI_ENABLE_MANPAGES=OFF \
      -DJPEGLI_FORCE_SYSTEM_GTEST=ON ..

3. Once built, install the plugin into GIMP:
   • Download and install GIMP (e.g., version 2.10.24).
   • Create the directory: C:\Program Files\GIMP 2\lib\gimp\2.0\plug-ins\file-jxl
   • Copy build/plugins/gimp/file-jxl.exe into that folder.

To test or review a Pull Request submitted by another user on your local machine, fetch the specific PR head using the PR number (NNNN):

git fetch origin refs/pull/NNNN/head
git checkout FETCH_HEAD

If git branch -vv shows that your branch is "behind" origin/main, you should rebase your changes on top of the latest upstream commits to maintain a linear history.

To perform a fetch and a rebase in a single step, use:

git pull -r

Alternatively, if you have already fetched, you can run git rebase to apply your current branch's commits on top of the tracking branch.

To use clang, first install the appropriate packages from the MSYS environment (e.g., for x86_64):

mingw-w64-x86_64-clang
mingw-w64-x86_64-clang-tools-extra
mingw-w64-x86_64-clang-compiler-rt

Once installed, you can build jpegli using the ./ci.sh script:

./ci.sh opt -DBUILD_TESTING=OFF -DBUILD_SHARED_LIBS=OFF \
    -DJPEGLI_ENABLE_BENCHMARK=OFF -DJPEGLI_ENABLE_MANPAGES=OFF \
    -DJPEGLI_FORCE_SYSTEM_GTEST=ON