Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 12 additions & 10 deletions .github/prompts/upgrade-dependency.prompt.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,30 +13,32 @@ Ask which dependency and which target version if not already stated.
owned wrapper — the `files_*` decoder, [av_format.cpp](../../src/av_format.cpp),
[metadata_xmp.cpp](../../src/metadata_xmp.cpp), [util_spell.cpp](../../src/util_spell.cpp) or
[util_zip.cpp](../../src/util_zip.cpp). If a fix seems to require editing the library's source, it
belongs in the wrapper, the build configuration or, for FFmpeg, a commit on the fork.
belongs in the wrapper or the build configuration, or upstream: Diffractor keeps no fork.

2. **Inventory the integration patches first.** Read [third-party.md](../../docs/third-party.md) for
this dependency and list every patch, why it exists, and the test that catches its loss. Several
are invisible until one specific test fails — that is the point of the list, and it is the thing
a rebase silently drops.
2. **Inventory the integration constraints first.** Read [third-party.md](../../docs/third-party.md)
for this dependency and list every constraint, why it exists, and the test that catches its loss.
Several are invisible until one specific test fails — that is the point of the list, and it is the
thing an upgrade silently drops.

3. **Rebase, then re-apply.** For FFmpeg, the configuration is compared by
3. **Regenerate, then re-apply.** For FFmpeg, the Windows configuration in
`cmake/vendored/ffmpeg-windows` is regenerated for the new version and compared with Linux's by
`tools/compare_ffmpeg_config.py`, which CI runs. The guard is not "no divergence" but "no
divergence that has not been accounted for": record any new platform switch beside the fork.
divergence that has not been accounted for": record any new platform switch beside the Windows
configuration.

4. **Prove it through the wrapper, not the library.** The library's own suite says nothing about
Diffractor's integration. Run `/test:*metadata*`, `/test:*video*`, `/test:*audio*` and the format
tests in [test_files.cpp](../../src/test_files.cpp), plus anything the patch list named.

5. **Move the pin and update the document.** Put the new archive's URL and SHA-256 in
`cmake/dd-dependencies.json`, and record the new version, any patch that changed shape, and any
patch that is no longer needed because upstream took it.
`cmake/dd-dependencies.json`, and record the new version, any constraint that changed shape, and
any that is no longer needed because upstream took it.

6. **Full validation**, because a dependency change has no narrow blast radius:

```powershell
.\dd.ps1 test
```

Report: the version moved from and to, each patch re-applied or retired, the tests run, and anything
Report: the version moved from and to, each constraint kept or retired, the tests run, and anything
you could not verify — an ARM64 or Linux path you did not build is worth saying out loud.
2 changes: 1 addition & 1 deletion .github/workflows/linux.yml
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ jobs:
- name: Run tests
run: bash ./dd test

# The fork is configured twice and nothing else notices when the two answers drift. It only
# FFmpeg is configured twice and nothing else notices when the two answers drift. It only
# needs one configuration, since the comparison is against the checked-in Windows config.
- name: Compare FFmpeg configurations
if: matrix.config == 'Release'
Expand Down
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ Start from the concrete failing behavior, symbol, test, or file, then route to t

- `app*`: application coordination; `view*`/`ui*`: views, controls, layout, drawing.
- `model*`: state, index, search, SQLite, properties; `files*`/`metadata*`: I/O, codecs, EXIF/IPTC/XMP/ICC.
- `av*`: audio/video; `render*`: surfaces/color/transforms; `platform_win_d3d11.cpp`/`platform_win_software.cpp`: draw backends.
- `av*`: audio/video; `render*`: software rasterisers for the sidebar's charts and globe and for panoramas. The draw backends and surfaces are libdesktop's render module.
- `platform*`: the app's own Windows and Linux glue - its side of FFmpeg's hardware decoding, its resource script, its Linux entry point; `util*`: the app's own helpers; `test*`: tests. The foundation (`df::`, `str::`) and the OS services (`platform.h`) are libdesktop's system module, and the desktop UI - `ui.h`, `platform_render.h`, the window layer and the renderers - its render module, all included as `libdesktop/<file>.h` - see [cmake/DiffractorLibdesktop.cmake](cmake/DiffractorLibdesktop.cmake).

Editing a file under `src/` also loads the matching rules in `.github/instructions/`, which carry the threading, rendering, view, test, and platform detail for that area at the point it applies.
Expand Down
17 changes: 9 additions & 8 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -166,16 +166,16 @@ diffractor_dependency(archive PKG_CONFIG libarchive VENDORED_MODULE vendored/arc
diffractor_dependency(bzip2 VENDORED_MODULE vendored/bzip2 OPTIONAL)
diffractor_dependency(lzma VENDORED_MODULE vendored/lzma OPTIONAL)

# Tracked music. Declared before the forks because FFmpeg's configure enables its libopenmpt
# demuxer only when it can already see the library, and a dependency can only be stated on a target
# that already exists.
# Tracked music. Declared before FFmpeg because its configure enables the libopenmpt demuxer only
# when it can already see the library, and a dependency can only be stated on a target that already
# exists.
diffractor_dependency(openmpt VENDORED_MODULE vendored/openmpt OPTIONAL)

# The fork. Never resolvable from the system: docs/third-party.md records the patches a distribution
# copy would silently discard. Not OPTIONAL: media is not a feature Diffractor is valid without, so a
# configuration that cannot build it fails here rather than producing an application that reports
# every media file as absent.
diffractor_dependency(ffmpeg FORK VENDORED_MODULE vendored/FFmpeg)
# FFmpeg, built as docs/third-party.md configures it. Never resolvable from the system: a
# distribution's copy is configured otherwise. Not OPTIONAL: media is not a feature Diffractor is
# valid without, so a configuration that cannot build it fails here rather than producing an
# application that reports every media file as absent.
diffractor_dependency(ffmpeg NO_SYSTEM VENDORED_MODULE vendored/FFmpeg)

# The foundation, OS services and desktop UI Diffractor is written in, fetched from libdesktop: see
# cmake/DiffractorLibdesktop.cmake.
Expand Down Expand Up @@ -220,6 +220,7 @@ set(DIFFRACTOR_PORTABLE_SOURCES
src/files_formats.cpp
src/files_psd.cpp
src/files_scan_photo.cpp
src/files_scan_media.cpp
src/files_jpeg.cpp
src/files_png.cpp
src/files_webp.cpp
Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,8 +28,8 @@ git clone https://github.com/ZacWalk/diffractor.git
```

The build uses CMake and requires Visual Studio and Ninja. CMake fetches the dependencies at the
versions `cmake/dd-dependencies.json` pins, Diffractor's [FFmpeg](https://github.com/ZacWalk/FFmpeg)
fork among them.
versions `cmake/dd-dependencies.json` pins, upstream [FFmpeg](https://github.com/FFmpeg/FFmpeg)
among them.

Everything goes through the `dd` gateway, which finds Visual Studio, configures with Ninja and puts the binary in `exe/`:

Expand Down
21 changes: 10 additions & 11 deletions cmake/DiffractorDependency.cmake
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,7 @@
# Purpose: Resolve one third-party dependency, either from a system package or from the release
# its owned module in cmake/vendored/ fetches, at the pin in cmake/dd-dependencies.json, and builds.
# The choice is per library because it is genuinely case by case -- see docs/third-party.md. FFmpeg
# is a Diffractor fork whose value is the patches it carries, so it is never offered a system option
# at all.
# is built as Diffractor configures it, so it is never offered a system option at all.

include_guard(GLOBAL)

Expand All @@ -16,8 +15,8 @@ find_package(PkgConfig QUIET)
# them statically would move CVE patching from the distribution onto us.
option(DIFFRACTOR_STATIC_VENDORED "Build vendored third-party libraries as static archives" ON)

# A shipped Diffractor is fully vendored: docs/third-party.md records the patches and the pinned
# versions a distribution copy would silently discard, and the vendored zlib is zlib-ng rather than
# A shipped Diffractor is fully vendored: docs/third-party.md records the pinned versions and the
# configuration a distribution copy would silently discard, and the vendored zlib is zlib-ng rather than
# zlib at all. System packages remain available per library, as a way to bring a new platform up
# before its vendored modules build, not as the configuration anything ships in.
option(DIFFRACTOR_PREFER_SYSTEM "Default each dependency to the system copy where one is offered" OFF)
Expand All @@ -29,20 +28,20 @@ set(DIFFRACTOR_RESOLVED_MISSING "" CACHE INTERNAL "")
# diffractor_dependency(<name>
# PKG_CONFIG <module>... pkg-config module(s) for the system copy
# VENDORED_MODULE <module> owned cmake/ module that defines diffractor::<name>
# [FORK] never resolvable from the system
# [NO_SYSTEM] never resolvable from the system
# [OPTIONAL] absence is reported, not fatal
# )
#
# Defines the imported target diffractor::<name> when the dependency resolves.
function(diffractor_dependency NAME)
cmake_parse_arguments(DEP "FORK;OPTIONAL" "VENDORED_MODULE" "PKG_CONFIG" ${ARGN})
cmake_parse_arguments(DEP "NO_SYSTEM;OPTIONAL" "VENDORED_MODULE" "PKG_CONFIG" ${ARGN})

string(TOUPPER "${NAME}" UPPER)
set(TARGET_NAME "diffractor::${NAME}")

if (DEP_FORK)
# No option is declared: a system copy of a fork silently discards the patches that are
# the entire reason it is vendored.
if (DEP_NO_SYSTEM)
# No option is declared: a distribution's copy is configured otherwise - with GPL components,
# typically, which would change the outbound licence - and is the wrong library to ship.
set(USE_SYSTEM OFF)
else ()
option(DIFFRACTOR_SYSTEM_${UPPER}
Expand Down Expand Up @@ -77,9 +76,9 @@ function(diffractor_dependency NAME)
set(DIFFRACTOR_RESOLVED_MISSING "${DIFFRACTOR_RESOLVED_MISSING};${NAME}" CACHE INTERNAL "")

if (NOT DEP_OPTIONAL)
if (DEP_FORK)
if (DEP_NO_SYSTEM)
message(FATAL_ERROR
"Fork '${NAME}' did not resolve, and it has no system or stubbed alternative.\n"
"'${NAME}' did not resolve, and it has no system or stubbed alternative.\n"
" module: cmake/${DEP_VENDORED_MODULE}.cmake")
endif ()

Expand Down
4 changes: 3 additions & 1 deletion cmake/DiffractorFetch.cmake
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ include_guard(GLOBAL)
include(FetchContent)

function(diffractor_fetch NAME)
# file(READ) is not tracked: without this a pin change would leave the build on the old archive.
set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS "${CMAKE_SOURCE_DIR}/cmake/dd-dependencies.json")
file(READ "${CMAKE_SOURCE_DIR}/cmake/dd-dependencies.json" _pins)
string(JSON _url ERROR_VARIABLE _missing GET "${_pins}" dependencies ${NAME} url)

Expand All @@ -25,7 +27,7 @@ function(diffractor_fetch NAME)
URL "${_url}"
URL_HASH SHA256=${_sha256}
SOURCE_SUBDIR no-cmake-project
DOWNLOAD_EXTRACT_TIMESTAMP TRUE)
DOWNLOAD_EXTRACT_TIMESTAMP FALSE)
FetchContent_MakeAvailable(${NAME})
set(${NAME}_SOURCE_DIR "${${NAME}_SOURCE_DIR}" PARENT_SCOPE)
endfunction()
19 changes: 13 additions & 6 deletions cmake/DiffractorHeif.cmake
Original file line number Diff line number Diff line change
Expand Up @@ -17,18 +17,25 @@ if (NOT libheif_POPULATED OR NOT TARGET libfiles-heif)
message(FATAL_ERROR "libfiles did not bring libheif: build libfiles with LIBFILES_HEIF")
endif ()

# FFmpeg's headers, from the fork FFmpeg.cmake fetched.
FetchContent_GetProperties(ffmpeg)

if (NOT ffmpeg_POPULATED)
message(FATAL_ERROR "FFmpeg was not fetched, and libheif's FFmpeg decoder plugin needs its headers")
# FFmpeg's headers as its own target exposes them: on Windows its source and the configuration kept in
# cmake/vendored/ffmpeg-windows, elsewhere the headers its build installs, which have to be there first.
if (TARGET diffractor_ffmpeg_msvc)
set(_heif_ffmpeg diffractor_ffmpeg_msvc)
elseif (TARGET diffractor_ffmpeg)
set(_heif_ffmpeg diffractor_ffmpeg)
else ()
message(FATAL_ERROR "FFmpeg was not resolved, and libheif's FFmpeg decoder plugin needs its headers")
endif ()

add_library(diffractor_heif_ffmpeg STATIC "${libheif_SOURCE_DIR}/libheif/plugins/decoder_ffmpeg.cc")
target_include_directories(diffractor_heif_ffmpeg PRIVATE
"${libheif_SOURCE_DIR}/libheif"
"${libheif_SOURCE_DIR}/libheif/plugins"
"${ffmpeg_SOURCE_DIR}")
"$<TARGET_PROPERTY:${_heif_ffmpeg},INTERFACE_INCLUDE_DIRECTORIES>")

if (TARGET ffmpeg_external)
add_dependencies(diffractor_heif_ffmpeg ffmpeg_external)
endif ()
target_compile_definitions(diffractor_heif_ffmpeg PRIVATE
HAVE_FFMPEG_DECODER ENABLE_MULTITHREADING_SUPPORT=1 ENABLE_PARALLEL_TILE_DECODING=1 IS_BIG_ENDIAN=0
_CRT_NONSTDC_NO_DEPRECATE)
Expand Down
2 changes: 1 addition & 1 deletion cmake/DiffractorLibdesktop.cmake
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
include_guard(GLOBAL)
include(FetchContent)

set(DIFFRACTOR_LIBDESKTOP_REVISION e7237cb2323b1638fec8f9c3b0165e28c50c0584)
set(DIFFRACTOR_LIBDESKTOP_REVISION 3d3b61378fc79444ba297abbb0b860793c72b2d3)

if (NOT DEFINED FETCHCONTENT_SOURCE_DIR_LIBDESKTOP AND EXISTS "${CMAKE_SOURCE_DIR}/../libdesktop/CMakeLists.txt")
set(FETCHCONTENT_SOURCE_DIR_LIBDESKTOP "${CMAKE_SOURCE_DIR}/../libdesktop" CACHE PATH
Expand Down
2 changes: 1 addition & 1 deletion cmake/DiffractorLibfiles.cmake
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
include_guard(GLOBAL)
include(FetchContent)

set(DIFFRACTOR_LIBFILES_REVISION 3a21f6c98ba92664bc5991e1ca80037da93901c9)
set(DIFFRACTOR_LIBFILES_REVISION f5cd78fc6807ece846b92e23eab46b565a50c084)

if (NOT DEFINED FETCHCONTENT_SOURCE_DIR_LIBFILES AND EXISTS "${CMAKE_SOURCE_DIR}/../libfiles/CMakeLists.txt")
set(FETCHCONTENT_SOURCE_DIR_LIBFILES "${CMAKE_SOURCE_DIR}/../libfiles" CACHE PATH
Expand Down
24 changes: 12 additions & 12 deletions cmake/dd-dependencies.json
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,8 @@
"method": "application"
},
"sqlite": {
"url": "https://www.sqlite.org/2026/sqlite-amalgamation-3530400.zip",
"sha256": "1e71ddf93849c6a6ecf58b827c0692073d2dd7ee40196158068f7b29f422e87d",
"url": "https://www.sqlite.org/2026/sqlite-amalgamation-3540100.zip",
"sha256": "0a9c8e34352dad46006aa82836d5383bff9dc6bc9ce5a60553c05aa30e6ad1f9",
"method": "application"
},
"minizip": {
Expand All @@ -22,13 +22,13 @@
"method": "application"
},
"libarchive": {
"url": "https://github.com/libarchive/libarchive/releases/download/v3.8.9/libarchive-3.8.9.tar.gz",
"sha256": "f5a6539059cf5e597dbeda37bfa4874b1e8dea063c8d93bf85a2b44af90a5bd4",
"url": "https://github.com/libarchive/libarchive/releases/download/v3.8.11/libarchive-3.8.11.tar.gz",
"sha256": "900fe9fc7237c2b04f090f3c3648de8fe597525771f5035016537ce2d667d12b",
"method": "application"
},
"hunspell": {
"url": "https://github.com/hunspell/hunspell/releases/download/v1.7.4/hunspell-1.7.4.tar.gz",
"sha256": "66ec82a577395fe9d471504267e6dd04615c76517c61af7c6b9c19e5e34e73c8",
"url": "https://github.com/hunspell/hunspell/releases/download/v1.7.6/hunspell-1.7.6.tar.gz",
"sha256": "9c650ace31d4d8cc1da925a9507c3de1d50f1a54857af2f72429f517d5d53467",
"method": "application"
},
"openmpt": {
Expand All @@ -37,8 +37,8 @@
"method": "application"
},
"ffmpeg": {
"url": "https://github.com/ZacWalk/FFmpeg/archive/eea8d39cc97af0ab398c23a2b2dc45efd8148159.tar.gz",
"sha256": "38faca6d27aa153436e8f495e0733739e486dc54466ffca2b6a287f43eb5c51a",
"url": "https://github.com/FFmpeg/FFmpeg/archive/a3c5339578cb1d54322e06b6bd1c8852fc6abc29.tar.gz",
"sha256": "9ce04bf74f17d29343834e8317066e818be5bd54de82b8be4e6bb1e8a212fd48",
"method": "application"
},
"nasm": {
Expand All @@ -47,13 +47,13 @@
"method": "application"
},
"7zr": {
"url": "https://github.com/ip7z/7zip/releases/download/26.03/7zr.exe",
"sha256": "ad4c82fadcbdf93c03b4fc440f300509c7d60c5c2f4d183e35d9d70d6957037d",
"url": "https://github.com/ip7z/7zip/releases/download/26.05/7zr.exe",
"sha256": "9bf582b894dfa665f852d7e9112b02290a1c303c2d95a21fcdc41ffcb03143b7",
"method": "application"
},
"7zip-extra": {
"url": "https://github.com/ip7z/7zip/releases/download/26.03/7z2603-extra.7z",
"sha256": "191894e6acb3647ffb69ce630479ff318523b2e2b9890aa7f05c1127c2e59b8f",
"url": "https://github.com/ip7z/7zip/releases/download/26.05/7z2605-extra.7z",
"sha256": "f27a8f103c84785026edcba1f67faf1357225df9d19ddb0b7760d55947141bc7",
"method": "application"
}
}
Expand Down
Loading
Loading