ImHex 딥다이브
— 바이트에 이름을 붙이면 파일의 설계도가 보인다

1프로젝트 한줄 요약

ImHex는 16진수 편집기와 구조 해석기를 한 화면에 결합한 오픈소스 프로그램입니다. 바이트를 수정하는 기본 기능에 Pattern Language, 디스어셈블러, 해시 계산, 데이터 시각화, YARA 규칙 검색, 플러그인이 붙습니다. 핵심은 파일을 숫자로 보여주는 데서 나아가, 그 숫자가 어떤 필드인지 사람이 설명할 수 있게 만든다는 점입니다.

1-1. 같은 바이트도 해석 규칙에 따라 의미가 달라진다

아래는 학습용으로 정의한 18바이트 형식입니다. 앞의 12바이트는 헤더이고, 뒤의 6바이트는 내용입니다. 01 00만 보고서는 이것이 숫자 1인지, 숫자 256인지, 서로 독립적인 두 값인지 알 수 없습니다. 데이터와 해석 규칙을 함께 알아야 의미가 생깁니다.

# 학습용 형식: IMHX 헤더 + 6바이트 내용
오프셋   바이트                                  의미
0x00     49 4D 48 58                             "IMHX"
0x04     01 00                                   버전 1
0x06     03 00                                   항목 수 3
0x08     06 00 00 00                             내용 길이 6
0x0C     41 42 43 44 45 46                       "ABCDEF"

ImHex의 Pattern Editor에 다음과 같은 규칙을 적으면, 각 구간을 필드 이름과 연결할 수 있습니다. u16은 2바이트 부호 없는 정수, u32는 4바이트 부호 없는 정수입니다. 이 예제는 Pattern Language 코드이며 C++ 코드와는 다릅니다.

#pragma endian little

struct DemoHeader {
    char magic[4];
    u16 version;
    u16 count;
    u32 payload_size;
};

DemoHeader header @ 0x00;

1-2. 이 저장소를 공부하면 연결되는 것들

• C++ 추상화: 파일·메모리·원격 데이터를 공통 인터페이스로 읽는 법.
• GUI 구조: 화면 코드를 등록하고 매 프레임 그리는 법.
• 언어 도구 통합: 별도 해석기에 읽기·쓰기 콜백을 공급하는 법.
• 제품 기반: 되돌리기, 작업 취소, 다국어, 배포, 테스트를 연결하는 법.

2왜 주목받는가

2-1. 트렌딩 순위와 상승 원인은 구분해서 읽자

2026-10-23 분석 기준 선정 위치는 GitHub Trending C++ Weekly #9입니다. 스타 55,522개와 포크 2,565개는 누적 관심을 보여주지만, 그 수치만으로 이번 주 유입 원인을 설명할 수는 없습니다. 특정 홍보·영상·신규 릴리스가 순위 상승을 일으켰다는 인과관계는 확인되지 않았습니다.

코드와 기능에서 읽을 수 있는 주목 포인트는 분명합니다. 바이트 편집, 구조 해석, 시각화, 확장 API가 하나의 데이터 인터페이스를 공유하므로 기능 사이를 오가며 분석할 수 있습니다. 여기에 구현 자체가 공개되어 있어 도구의 동작을 소스로 검증할 수 있다는 장점이 있습니다.

2-2. 경쟁 도구와는 무엇을 비교해야 할까

비교의 기준은 “무엇을 주로 읽을 것인가”입니다. 아래는 전체 성능 순위가 아니라 대표적인 작업 흐름의 비교입니다. 같은 기능이 여러 제품에 있어도 설계의 중심은 다를 수 있습니다.

010 Editor도 구조 해석을 지원하므로 “ImHex만 파일 구조를 읽는다”는 비교는 부정확합니다. 비교 근거는 010 Editor 공식 소개와 Ghidra 공식 소개입니다. ImHex의 학습상 강점은 그 기능이 연결되는 내부 코드를 끝까지 읽을 수 있다는 것입니다.

2-3. 한 기능이 여러 화면에서 재사용된다

plugins/builtin/source/content/views.cpp의 registerViews()는 ViewHexEditor, ViewPatternEditor, ViewPatternData, ViewInformation 등을 같은 등록 API에 넣습니다. 각 화면을 별도 프로그램으로 만들지 않고, 공통 환경 안에 배치하는 방식입니다.

확장도 같은 흐름을 따릅니다. plugins/disassembler/CMakeLists.txt는 Capstone과 별도 libdisassembler를 연결하고, plugins/decompress/CMakeLists.txt는 찾은 압축 라이브러리만 활성화합니다. 큰 제품이 기능별 의존성을 분리하는 사례입니다.

2-4. 최근 커밋을 읽을 때의 관찰 포인트

분석 대상 커밋은 2026-10-08의 34483cb이며, 제목은 Pattern Editor의 데이터 경쟁과 충돌 수정에 관한 것입니다. view_pattern_editor.cpp에는 런타임 잠금, 로그 잠금, 비동기 실행, UI 상태가 함께 나옵니다. 이 복잡함은 “화면이 있는 언어 도구”를 만들 때 동시성이 왜 중요한지 보여줍니다.

3기술 스택 전체 지도

이 프로젝트의 기본 실행 단위는 데스크톱 프로세스입니다. 웹 서비스에서 말하는 백엔드와 프론트엔드를 그대로 대입하기보다, 데이터·분석 계층 / 화면 계층 / 빌드·배포 계층으로 읽으면 명확합니다. 데이터베이스 서버나 Node.js 서버가 핵심 구성 요소인 구조는 아닙니다.

3-1. 백엔드에 해당하는 데이터·분석 계층

3.4.0 이상은 설치된 라이브러리의 확정 버전이 아니라 CMake의 최소 요구값입니다. 시스템 라이브러리를 쓰는 옵션과 동봉 코드를 쓰는 옵션도 다릅니다. 예를 들어 시스템 nlohmann/json은 find_package(nlohmann_json 3.10.2 REQUIRED)를 사용합니다.

3-2. 프론트엔드에 해당하는 화면 계층

main/gui/source/window/window.cpp에서 frameBegin()은 ImGui::NewFrame()을 호출하고, frame()은 등록된 뷰를 그리며, frameEnd()는 렌더링을 마무리합니다. HTML DOM을 갱신하는 웹 UI와는 다른 실행 흐름입니다.

3-3. 인프라·빌드·언어 확장

• CMake 3.25 이상: 루트 cmake_minimum_required()가 최종 기준입니다. CMakePresets.json의 3.20 표기만 보고 최소 버전을 판단하면 안 됩니다.
• Ninja·ccache: .github/workflows/tests.yml에서 빌드 실행과 컴파일 캐시를 담당합니다.
• GitHub Actions: 테스트 CI는 ubuntu-26.04, gcc-16·g++-16, actions/checkout@v7과 재귀 서브모듈 체크아웃을 명시합니다.
• vcpkg: dist/vcpkg.json의 builtin-baseline은 9e593bb18ea69cc5095e012465dcd675a822ed0d입니다. 파일의 version: 1.0.0은 ImHex 버전이 아닙니다.
• Emscripten: dist/web/Dockerfile의 빌드 이미지가 emscripten/emsdk:6.0.6입니다. C++를 WebAssembly로 빌드하며 별도 React 앱으로 다시 구현하는 방식이 아닙니다.
• C#·.NET: plugins/script_loader는 선택적 스크립트 지원입니다. FindCoreClrEmbed.cmake는 CORECLR_VERSION "10.0"을 찾으며, 전체 앱의 필수 런타임으로 해석하면 안 됩니다.

버전 숫자를 읽을 때는 앱 버전, 동봉 라이브러리 버전, 최소 요구 버전, 서브모듈 커밋을 구별해야 합니다. 이 구분만 익혀도 낯선 C++ 저장소의 빌드 오류를 훨씬 정확히 해석할 수 있습니다.

4아키텍처 심화 분석

4-1. 전체 흐름: 실행 파일은 환경을 만들고, 플러그인은 기능을 채운다

main/gui/source/main.cpp의 main()은 메인 스레드 ID, 충돌 처리, 네이티브 초기화, 인스턴스 간 메시징을 준비한 뒤 init::runImHex()로 들어갑니다. 데스크톱 구현은 GLFW 초기화, 시작 화면의 초기화 작업, 메인 Window::loop(), 정리 순서로 진행됩니다.

그림에서 중요한 연결은 런타임에서 Provider로 향하는 선입니다. 해석기는 파일 핸들을 직접 열지 않아도 됩니다. ImHex가 공급하는 읽기·쓰기 콜백을 통해 현재 데이터에 접근합니다. 전체 연결을 한 번 파악한 뒤 아래 네 가지 설계를 읽으면 세부 코드의 목적이 드러납니다.

4-2. 설계 ① 데이터 접근을 바꾸는 Provider 추상화

lib/libimhex/include/hex/providers/provider.hpp의 prv::Provider는 readRaw(), writeRaw(), getActualSize() 같은 인터페이스를 정의합니다. 화면이 구체적인 파일 구현 대신 이 인터페이스에 의존하므로 다른 데이터 원천을 붙일 수 있습니다. 같은 작업을 다른 구현에 맡기는 전략 교체의 관점으로 읽을 수 있습니다.

// Provider의 실제 선언 중 핵심 부분 발췌
virtual void read(u64 offset, void *buffer,
                  size_t size, bool overlays = true);
virtual void write(u64 offset, const void *buffer, size_t size);
virtual void readRaw(u64 offset, void *buffer, size_t size) = 0;
virtual void writeRaw(u64 offset, const void *buffer, size_t size) = 0;
[[nodiscard]] virtual u64 getActualSize() const = 0;

lib/libimhex/source/providers/provider.cpp의 Provider::read()는 기준 주소를 뺀 오프셋으로 readRaw()를 호출하고, 필요하면 오버레이를 적용합니다. 따라서 화면 주소와 파일 오프셋은 항상 같지 않습니다. 기준 주소가 0x1000이면 화면의 0x1004는 파일 오프셋 4에 해당합니다.

plugins/builtin/source/content/providers/file_provider.cpp의 FileProvider::open()은 기본 128_MiB 설정을 기준으로 접근 방식을 나눕니다. 그 이상이면 직접 파일 접근 경로를 선택하고, 처음에는 쓰기를 꺼 둔 뒤 화면에서 허용할 수 있게 합니다. 작은 일반 파일의 메모리 적재 경로와 큰 파일의 직접 접근 경로를 구별해야 합니다.

바이트 수정이 실제 저장소까지 가는 경로

Provider::write()는 곧바로 writeRaw()를 호출하지 않습니다. 먼저 변경 이벤트를 발행합니다. ViewPatches가 이를 받아 이전·이후 바이트를 보관하는 OperationWrite를 만들고, 되돌리기 스택이 작업을 적용합니다.

근거는 plugins/builtin/source/content/views/view_patches.cpp, plugins/builtin/include/content/providers/undo_operations/operation_write.hpp, lib/libimhex/source/providers/undo/stack.cpp입니다. Stack::add()는 redo 기록을 비우고 새 작업의 redo()를 실행합니다. 새 편집 뒤에 예전 redo가 사라지는 이유를 코드로 설명할 수 있습니다.

4-3. 설계 ② 플러그인과 Registry·Factory

lib/libimhex/source/api/plugin_manager.cpp의 Plugin::Plugin(path)는 Windows에서는 LoadLibraryW(), 다른 데스크톱 환경에서는 dlopen()으로 라이브러리를 읽고 initializePlugin 등의 진입점을 찾습니다. Plugin::initializePlugin()은 요청한 호환 버전을 검사한 뒤 초기화 함수를 호출합니다.

기본 기능도 예외가 아닙니다. plugins/builtin/source/plugin_builtin.cpp의 IMHEX_PLUGIN_SETUP_BUILTIN 안에서 registerProviders(), registerViews(), registerPatternLanguageFunctions() 등을 호출합니다. 실행 파일에 기능을 직접 늘어놓기보다 등록 API를 통해 채우는 구조입니다.

// plugins/builtin/source/content/providers.cpp 발췌
ContentRegistry::Provider::add<FileProvider>(true);
ContentRegistry::Provider::add<IntelHexProvider>();
ContentRegistry::Provider::add<MemoryFileProvider>(true);

// plugins/builtin/source/content/views.cpp 발췌
ContentRegistry::Views::add<ViewHexEditor>();
ContentRegistry::Views::add<ViewPatternEditor>();

ContentRegistry::Provider::add<T>()는 타입 이름과 생성 함수를 등록합니다. ContentRegistry::Views::add<T>()는 뷰 객체를 만들어 등록합니다. 둘 다 std::derived_from 제약을 써서 올바른 기반 클래스를 상속한 타입만 받습니다. 등록소는 “무엇이 있는가”를 관리하고, 팩토리는 “어떻게 만들 것인가”를 담당합니다.

웹 빌드는 같은 플러그인을 모두 동적으로 읽는다고 보면 안 됩니다. dist/web/Dockerfile은 IMHEX_STATIC_LINK_PLUGINS=ON을 지정하고 script_loader;remote를 제외합니다. 플랫폼에 따라 확장 기능의 묶음과 로딩 방식이 달라집니다.

4-4. 설계 ③ 발행·구독으로 화면 사이 연결하기

lib/libimhex/include/hex/api/event_manager.hpp에는 subscribe(), unsubscribe(), post()가 있습니다. 한 기능이 이벤트를 보내면 구독한 기능들이 반응합니다. 예를 들어 편집 계층은 변경 이벤트를 보내고, 패치 화면은 그것을 받아 편집 이력을 관리합니다.

// 학습용 의사 코드: 이벤트의 흐름만 요약
EventProviderDataModified::subscribe(owner, onBytesChanged);
EventProviderDataModified::post(provider, offset, size, bytes);
EventProviderDataModified::unsubscribe(owner);

여기서 post()라는 이름에 주의하세요. 구현은 해당 이벤트의 구독 목록을 순회하며 현재 호출 스레드에서 콜백을 직접 실행합니다. 메시지를 큐에 넣고 나중에 처리하는 비동기 버스가 아닙니다. std::recursive_mutex를 사용한다는 사실도 모든 구독자 상태의 안전을 자동으로 보장하지는 않습니다.

배울 점은 “발행자는 구독자를 몰라도 된다”는 결합도 완화와 그 대가입니다. 호출 관계가 파일 사이로 흩어지므로, 이벤트 이름을 검색해 구독자까지 함께 읽어야 실제 실행 경로가 보입니다. 객체가 사라질 때 구독 해제도 살펴봐야 합니다.

4-5. 설계 ④ 작업 큐와 UI 반영 경계

lib/libimhex/source/api/task_manager.cpp의 TaskManager::init()은 hardware_concurrency() 값에 따라 std::jthread 작업자를 만들고, 조건 변수와 작업 큐를 사용합니다. 긴 해석 작업을 화면 루프와 분리하는 기반입니다.

ViewPatternEditor::evaluatePattern()의 중요한 단계는 다음과 같습니다. 근거 파일은 plugins/builtin/source/content/views/view_pattern_editor.cpp입니다.

1. getRuntimeLock()을 잡고 런타임과 화면의 이전 실행 상태를 정리합니다.
2. TaskManager::createTask()에 평가 작업을 넘깁니다.
3. 작업 안에서 configureRuntime(runtime, provider)로 데이터 원천을 연결합니다.
4. 중단 콜백·로그 콜백·위험 함수 호출 처리기를 설정하고 runtime.executeString()을 호출합니다.
5. 완료 뒤 TaskManager::doLater()를 통해 EventPatternExecuted 발행을 예약합니다.

// configureRuntime()의 데이터 연결 부분 발췌
runtime.setDataSource(
    provider->getBaseAddress(), provider->getActualSize(),
    [provider](u64 offset, u8 *buffer, size_t size) {
        provider->read(offset, buffer, size);
    },
    [provider](u64 offset, const u8 *buffer, size_t size) {
        if (provider->isWritable())
            provider->write(offset, buffer, size);
    }
);

TaskManager::doLater()는 콜백을 별도 목록에 저장하고, 화면의 Window::frameBegin()에서 runDeferredCalls()가 이를 실행합니다. 작업을 큐에 넣는 API와 이벤트를 즉시 발행하는 API를 구분해야 UI 스레드를 잘못 건드리지 않습니다.

새 기능을 읽을 때는 데이터가 어디서 오고, 누가 상태를 소유하며, 어느 스레드에서 결과가 반영되는지를 함께 추적하세요. 이 세 질문으로 GUI·플러그인·언어 런타임의 연결을 설명할 수 있습니다.

5디렉토리 구조 해부

5-1. 이름이 비슷한 세 계층을 구별하자

• main/gui는 창과 실행 수명을 관리합니다. 헥스 편집 기능 전체가 이곳에 있는 것은 아닙니다.
• lib/libimhex는 여러 플러그인이 공유할 계약과 기반 기능을 제공합니다.
• plugins/builtin은 그 계약을 이용해 실제 제품의 주요 화면과 기능을 구성합니다.

예를 들어 버튼을 눌렀을 때 동작을 찾고 싶다면 main.cpp부터 전부 읽기보다 plugins/builtin/source/content/views/에서 화면을 찾으세요. 그 화면이 호출하는 hex/api와 Provider를 거슬러 올라가면 범위를 좁힐 수 있습니다.

5-2. 코드 규모: 외부 코드와 앱 코드를 나누어 보기

아래는 커밋 34483cb의 파일을 확장자별로 센 물리 줄 수입니다. 줄바꿈 문자 LF를 세므로 마지막에 줄바꿈이 없는 줄은 제외합니다. 빈 줄·주석을 포함하며, lib/third_party/와 lib/external/은 제외했습니다. 글꼴·아이콘 헤더 등 선언이 많은 파일은 포함되므로 순수 기능 구현량과 같지는 않습니다.

C++·공통 헤더의 집계 대상은 .cpp·.hpp·.h·.cppm입니다.

외부 디렉터리까지 포함해 존재하는 C++·헤더 파일을 세면 738개, 473,305줄입니다. 이 차이는 동봉 GUI·JSON 등 외부 코드의 비중을 보여줍니다. 미전개 서브모듈 본체는 어느 수치에도 포함되지 않으므로 전체 의존성까지 합친 완전한 제품 코드량이라고 부를 수 없습니다.

디렉터리별 줄 수를 먼저 나누면, 수십만 줄의 저장소도 지금 읽을 책임 범위로 좁힐 수 있습니다. 처음에는 main 전체보다 Provider → FileProvider → configureRuntime의 짧은 경로부터 읽는 편이 좋습니다.

6학습 포인트 (기술별)

6-1. C++ 타입·소유권: 누구의 객체인가

ContentRegistry::Views::add()는 std::make_unique<T>()로 뷰를 만들고 등록소에 넘깁니다. Provider 생성 API에는 std::shared_ptr도 등장합니다. 같은 스마트 포인터라도 소유자가 하나인가, 여러 곳이 함께 수명을 유지해야 하는가라는 질문은 다릅니다.

실습 아이디어: lib/libimhex/include/hex/api/content_registry/views.hpp와 lib/libimhex/include/hex/api/content_registry/provider.hpp를 나란히 읽고, 생성 함수의 반환 타입과 보관 타입을 표로 정리하세요. 이어서 런타임 콜백의 [provider] 캡처가 데이터 자체의 복사인지 포인터 값의 복사인지 설명해 보세요. 포인터를 캡처한다고 대상의 수명이 자동 연장되는 것은 아닙니다.

6-2. 바이너리 해석: 엔디언과 길이 필드

앞의 예제에서 01 00은 little endian u16으로 1입니다. 순서를 반대로 해석하면 256이 됩니다. C++ 구조체의 sizeof는 패딩 때문에 파일 형식의 길이와 다를 수 있으므로, 파일의 레이아웃과 메모리 레이아웃을 혼동하지 마세요.

실습 아이디어: tests/algorithms/source/endian.cpp의 changeEndianness<u32>() 검사와 tests/helpers/source/encoding.cpp의 UTF-16 LE·BE 사례를 읽으세요. 같은 바이트가 정수·문자·문자열 중 무엇으로 해석되는지 별도로 적어 보면 바이트 순서와 문자 인코딩의 차이가 보입니다.

6-3. GUI: 화면 상태는 어디에 남는가

ImGui의 즉시 모드에서는 매 프레임 UI를 기술합니다. 그렇다고 사용자 상태가 사라지는 것은 아닙니다. 파일별 콘솔·편집기 상태는 PerProvider<T> 같은 저장 공간에 남습니다. lib/libimhex/include/hex/providers/provider_data.hpp에서 Provider 열기 이벤트와 상태 생성의 연결을 볼 수 있습니다.

실습 아이디어: 두 파일을 연 상황을 종이에 그려 보세요. 탭 A의 오류 메시지가 탭 B에 보이지 않으려면 어떤 상태가 전역이고 어떤 상태가 Provider별이어야 할지 분류합니다. 그 뒤 view_pattern_editor.cpp의 .get(provider) 호출을 찾아 예상과 비교하세요.

6-4. 동시성: 취소와 완료도 설계의 일부다

Task::update()는 진행률을 갱신하면서 중단 요청을 확인하고, 요청이 있으면 TaskInterruptor를 던집니다. 취소 버튼을 만드는 일은 버튼만 그리는 일이 아닙니다. 반복 작업이 적절한 간격으로 취소 상태를 확인해야 합니다.

실습 아이디어: Task::interrupt(), Task::update(), 작업자의 예외 처리 분기를 이어 읽으세요. “중단 요청 → 작업의 확인 → 정리 → 완료 상태 반영”을 네 칸 도식으로 정리합니다. 잠금을 오래 잡을 때 어떤 화면 동작이 기다릴지도 예상해 보세요.

6-5. 통계: 엔트로피는 판정이 아니라 관찰값이다

InformationByteAnalysis::process()는 선택한 영역을 한 번 순회하면서 바이트 분포·종류 분포·구간 엔트로피를 함께 갱신합니다. 파일은 plugins/builtin/source/content/data_information_sections.cpp입니다. 엔트로피 구간 크기 설정이 0이면 256바이트를 사용합니다.

# diagrams.hpp의 calculateEntropy()를 수식으로 풀면
p[b] = 바이트 b의 등장 횟수 / 구간의 바이트 수
H = -sum(p[b] * log2(p[b]))
화면에 쓰는 정규화 값 = min(1, H / 8)

# 같은 바이트만 반복: 0에 가까움
# 256종류가 고르게 등장: 1에 가까움

수식 구현은 plugins/builtin/include/content/helpers/diagrams.hpp의 DiagramChunkBasedEntropyAnalysis::calculateEntropy()에 있습니다. 화면의 힌트는 평균값이 0.83보다 크고 최고 구간값이 0.9보다 클 때 나타납니다. 압축 데이터와 암호화 데이터는 모두 높은 값을 보일 수 있으므로 그 숫자만으로 암호화 여부를 확정할 수 없습니다.

실습 아이디어: 0만 반복하는 파일과 0~255가 반복하는 파일을 같은 길이로 준비한다고 가정하고 분포를 먼저 예상하세요. 구간 길이를 줄였을 때 값이 어떻게 달라질지도 설명해 보면 통계의 표본 크기를 배울 수 있습니다.

6-6. MCP·JSON-RPC: 화면 기능을 외부 도구로 노출하기

이 커밋에는 MCP 연동도 있습니다. plugins/builtin/source/content/mcp_tools.cpp는 파일 열기·열린 데이터 목록·데이터 선택·읽기 도구를 등록합니다. ViewPatternEditor::registerHandlers()에는 패턴 실행·콘솔 조회·결과 조회 도구 등록도 있습니다.

plugins/builtin/romfs/mcp/tools/read_data.json은 입력 스키마를 정의하며, 구현은 한 번의 읽기를 16_MiB로 제한하고 결과 바이트를 Base64로 돌려줍니다. 여기서 Base64는 암호화가 아니라 JSON 문자열로 옮기기 위한 인코딩입니다.

실습 아이디어: 읽기 도구의 스키마와 콜백을 비교해 보세요. “문법상 숫자”라는 조건과 “현재 파일 범위에 들어가는 유효한 주소”라는 조건을 구분해 입력 검증 표를 만듭니다. 서버 구현의 JSON-RPC 오류 처리만으로 모든 도구 인자가 검증된다고 가정하지 않는 것이 핵심입니다.

이 저장소의 학습 가치는 개별 라이브러리를 쓰는 법보다, 타입·상태·작업·입력 검증을 서로 연결하는 방법에 있습니다.

6-7. 테스트·CI: 정상값보다 경계를 먼저 읽자

tests/helpers/source/common.cpp의 TestProvider_read는 8바이트 데이터에서 오프셋 7부터 2바이트를 읽는 경계 초과 요청을 검사합니다. 대상 버퍼가 바뀌지 않는지도 확인합니다. 성공한 값만 비교하는 테스트보다 API의 실패 계약을 더 잘 드러냅니다.

.github/workflows/tests.yml은 AddressSanitizer·LeakSanitizer·UndefinedBehaviorSanitizer를 켜고 ctest --output-on-failure를 실행하도록 정의합니다. IMHEX_OFFLINE_BUILD=ON일 때 일부 네트워크 테스트는 tests/helpers/CMakeLists.txt에서 제외됩니다. 테스트 구성의 존재와 실제 통과 여부는 별개의 정보입니다.

7하드웨어 / 시스템 요구사항

7-1. 사용 환경: README의 최소 안내

-NoGPU 릴리스는 README 기준 소프트웨어 렌더링 대안입니다. GPU 가속보다 느릴 수 있습니다. 머신러닝 모델을 돌리는 도구가 아니므로 CUDA GPU나 대용량 VRAM을 기본 조건으로 삼을 이유는 없습니다.

7-2. 파일 크기만으로 메모리 사용량을 계산하면 안 된다

FileProvider::open()의 128_MiB는 메모리 적재 여부를 가르는 기본 설정값입니다. 전체 앱의 메모리 한도나 최대 파일 크기가 아닙니다. 패턴이 생성하는 객체 수, 문자열·배열 크기, 통계 버퍼, 이전·이후 바이트를 보관하는 편집 이력이 추가 비용을 만듭니다.

7-3. 개발 환경: 최소 검사값과 실제 CI 조합

루트 기준 CMake는 3.25 이상이며 C++23을 요구합니다. verifyCompiler()의 하한은 GCC 12·Clang 17이지만, Linux 테스트 CI와 Linux 빌드 안내는 GCC 16을 사용합니다. 최소 버전 검사를 통과하는 것과 모든 최신 코드가 성공적으로 컴파일되는 것은 같은 약속이 아닙니다.

서브모듈과 시스템 의존성도 필요합니다. detectBadClone()는 외부 의존성 디렉터리가 비어 있으면 오류를 냅니다. 빌드 학습에서는 먼저 .gitmodules, dist/compiling/, CI 설정을 읽고 툴체인 조합을 정리하는 것이 좋습니다. 구체적인 빌드 시간·필요 RAM·동시 작업 수는 CPU와 환경에 따라 달라 고정 수치로 보장할 수 없습니다.

7-4. 웹 버전의 범위

dist/web/Dockerfile은 의존성에도 -pthread를 붙이며 wasm32-emscripten을 사용합니다. 웹에서는 registerProviders()의 OS_WEB 조건 때문에 데스크톱과 같은 Provider가 모두 등록되지 않습니다. 브라우저 권한과 샌드박스가 있으므로 디스크·프로세스 메모리·원격 기능을 그대로 기대하면 안 됩니다.

8직접 해볼 수 있는 실습 과제

아래 다섯 과제는 읽기에서 시작해 작은 구현으로 확장합니다. 1~3번은 배포 앱과 별도 학습 파일을 사용할 수 있고, 4~5번은 소스를 수정할 수 있는 별도 실습 환경을 전제로 합니다. 과제의 완료 기준을 코드 작성량이 아니라, 입력을 바꿨을 때 결과가 왜 달라지는지 설명할 수 있는가로 잡으세요.

python3 - <<'PY'
from pathlib import Path
raw = bytes.fromhex(
    "49 4D 48 58 01 00 03 00 06 00 00 00 41 42 43 44 45 46"
)
Path("demo.bin").write_bytes(raw)
PY

char payload[header.payload_size] @ 0x0C;

9관련 기술 심화 학습 로드맵

주당 3~5시간 정도를 가정한 학습 제안입니다. C++가 처음이라면 1~2주차를 반복해도 좋습니다. 매주 새로운 기능을 늘리기보다, 같은 작은 바이너리를 더 깊은 계층에서 설명하는 방식으로 공부하세요.

9-1. 기반 지식이 부족할 때 돌아갈 지점

• virtual이 어렵다면 파일·메모리를 동일한 함수로 읽는 짧은 예제부터 복습합니다.
• 템플릿이 어렵다면 add<ViewHexEditor>()의 타입 인자가 무엇을 결정하는지 설명하는 데 집중합니다.
• 콜백이 어렵다면 “지금 결과를 받는 함수”와 “나중에 호출할 함수를 전달하는 API”를 구분합니다.
• 스레드가 어렵다면 객체별로 읽는 주체·쓰는 주체·수명 종료 주체를 먼저 표로 만듭니다.

9-2. 그다음에 확장할 세 방향

언어 도구에 관심이 있다면 별도 PatternLanguage 저장소의 렉서·파서·평가기와 오류 위치 전달을 공부합니다. ImHex의 연결 코드와 언어 본체를 구분해 읽는 것이 출발점입니다.

시스템 도구에 관심이 있다면 Provider의 주소 변환·파일 접근·권한·원격 데이터 경계를 공부합니다. 같은 읽기 인터페이스라도 지연 시간과 실패 방식은 달라집니다.

데스크톱 제품에 관심이 있다면 ImGui 프레임, 탭별 상태, 단축키, 로컬라이제이션, 패키징을 따라갑니다. 기능 구현 이후 사용자에게 전달하기까지 필요한 층을 배울 수 있습니다.

10핵심 키워드 사전

11참고 링크

11-1. 공식 저장소·문서

• ImHex 공식 저장소 · 기능 개요, 지원 환경, 설치 안내의 출발점.
• 릴리스 v1.38.1 · 개발 브랜치의 WIP 버전과 구별.
• ImHex 공식 문서 · 화면과 분석 기능 사용법.
• Pattern Language 공식 문서 · 구조·배열·배치·타입 문법.
• PatternLanguage 저장소 · 별도로 관리되는 언어 구현.
• ImHex-Patterns 저장소 · 파일 형식별 패턴과 관련 자료.
• 공식 플러그인 템플릿 · SDK 기반 확장 개발의 출발점.

11-2. 핵심 소스 다시 찾아가기

아래 링크의 파일 경로는 저장소 루트 기준이며, 모두 분석 커밋에 고정되어 있습니다. 함수 이름으로 검색하면 본문에서 설명한 연결을 확인할 수 있습니다.

• CMakeLists.txt · C++23, CMake 3.25, 기본 빌드 옵션.
• cmake/build_helpers.cmake · loadVersion(), detectBadClone(), verifyCompiler(), 의존성 구성.
• main/gui/source/main.cpp · 프로세스 진입점.
• main/gui/source/window/window.cpp · 프레임 시작·뷰 그리기·렌더링.
• lib/libimhex/include/hex/providers/provider.hpp · 데이터 접근 인터페이스.
• plugins/builtin/source/content/providers/file_provider.cpp · 메모리 적재·직접 접근·저장 분기.
• lib/libimhex/source/api/plugin_manager.cpp · 동적 로딩·호환 버전·초기화.
• lib/libimhex/include/hex/api/event_manager.hpp · 동기적인 이벤트 발행·구독.
• lib/libimhex/source/api/task_manager.cpp · 작업 큐·취소·지연 콜백.
• lib/libimhex/source/api/content_registry.cpp · configureRuntime()와 해석기의 데이터 연결.
• plugins/builtin/source/content/views/view_pattern_editor.cpp · 평가 작업·로그·MCP 도구.
• .github/workflows/tests.yml · GCC 16, sanitizer, CTest, 통합 테스트 정의.

11-3. 관련 기술의 공식 자료

• Dear ImGui · 즉시 모드 GUI의 API와 예제.
• ImPlot · GUI 안의 데이터 시각화.
• GLFW 문서 · 창·입력·그래픽 컨텍스트의 역할.
• CMake 문서 · 타깃·링크·의존성·빌드 옵션.
• Emscripten 문서 · 네이티브 코드를 웹으로 옮기는 툴체인.
• Capstone · 여러 CPU 아키텍처의 디스어셈블 엔진.
• YARA 문서 · 문자열·바이트 패턴·조건 작성.
• AddressSanitizer 문서 · 메모리 오류 검출의 동작과 범위.
• 010 Editor 공식 소개 · Binary Templates 비교 근거.
• Ghidra 공식 소개 · 역공학 프레임워크의 기능 범위 비교 근거.

현재 상태 (2026-10-23 GitHub 기준)

최근 push 날짜는 저장소의 갱신 시각이고 커밋 날짜는 해당 커밋에 기록된 시각이므로 서로 다를 수 있습니다. 코드 규모는 빈 줄·주석을 포함한 물리 줄 수이며, 날짜·스타·포크와 달리 위에서 정의한 소스 범위의 집계입니다.