O-MVLL Documentation

Instead of managing lists of function names in Python, you can opt functions into or out of specific obfuscation passes directly in C/C++ source code using __attribute__((annotate("..."))).

To make this work, you must use omvll.ObfuscationConfig.default_config within your config class and provide a matching string via the annotation keyword.

Precedence (Strongest to Weakest):

1. module_excludes
2. function_excludes
3. Negated annotation !<annotation>
4. function_includes
5. Annotation <annotation>
6. probability

Note: A negated annotation (e.g., !<flattening>) always wins, even over explicit includes or 100% probability.

// Opt into arithmetic obfuscation
__attribute__((annotate("arithmetic"))) 
// Opt into control-flow flattening
__attribute__((annotate("flattening"))) 
int verify_license(const char *token) { ... }

// Opt out of flattening, even if included in a list
__attribute__((annotate("!flattening"))) 
int hot_path(void) { ... }

# In your ObfuscationConfig implementation:
def obfuscate_arithmetic(self, mod, func):
    if omvll.ObfuscationConfig.default_config(self, mod, func, annotation="arithmetic"):
        return omvll.ArithmeticOpt(rounds=2)
    return omvll.ArithmeticOpt(False)

O-MVLL API documentation is generated using Sphinx with the autodoc extension. The documentation is not manually written in .rst files; instead, it is pulled directly from the C++ docstrings embedded in the pybind11 bindings.

To update or add documentation for a class, method, or attribute, you must edit the corresponding C++ docstring in the source code rather than the .rst files in doc/src/.

Key source files for API docstrings:

• src/core/python/PyConfig.cpp: Contains omvll.OMVLLConfig, omvll.Phase / omvll.Pass enums, and omvll.ObfuscationConfig callbacks.
• src/core/python/pyobf_opt.cpp: Contains the *Opt option classes.
• src/core/python/pyllvm.cpp: Contains Module, Function, Struct, and GlobalVariable.

Manual documentation in .rst files is reserved for items that are not class members, such as the omvll.config instance attribute, configuration Template (doc/src/config.rst, doc/src/obfuscation.rst), and version attributes (doc/src/versioning.rst).

To apply global settings across the O-MVLL pipeline, modify the attributes of the omvll.config instance within the omvll_get_config() function. This function should return your specific configuration object (e.g., an instance of omvll.ObfuscationConfig). Using @lru_cache(maxsize=1) is recommended to ensure the global configuration is initialized once and reused.

Available global configuration attributes in omvll.OMVLLConfig include:

• shuffle_functions: Boolean to enable/disable function shuffling.
• inline_jni_wrappers: Boolean to enable/disable inlining of JNI wrappers.
• global_mod_exclude: List of modules to exclude from global obfuscation.
• global_func_exclude: List of functions to exclude from global obfuscation.
• probability_seed: Seed for probabilistic obfuscation passes.
• output_folder: Destination directory for obfuscated outputs.
• pass_phases: A mapping that defines which obfuscation passes run during specific execution phases.

@lru_cache(maxsize=1)
def omvll_get_config() -> omvll.ObfuscationConfig:
    omvll.config.shuffle_functions = True
    omvll.config.inline_jni_wrappers = True
    omvll.config.pass_phases = {
        omvll.Pass.Arithmetic: {omvll.Phase.Early},
    }
    return MyConfig()

Building documentation on macOS requires Python 3.10 (due to pybind11 compatibility constraints) and a prebuilt dependency tree (LLVM 21.1.6, pybind11, spdlog).

Follow these steps:

1. Setup Sphinx environment: Create a virtual environment using Python 3.10 and install sphinx and furo.
2. Build the standalone module: Use cmake with -DOMVLL_PY_STANDALONE=1. You must provide paths to the downloaded dependencies (LLVM, pybind11, spdlog) and the Python 3.10 framework. On macOS, this produces build/omvll.so.
3. Generate HTML: Run sphinx-build while setting OMVLL_STANDALONE_DIR to your build directory.

# 1. Sphinx environment (Python 3.10)
python3.10 -m venv /tmp/omvll-doc-venv
/tmp/omvll-doc-venv/bin/pip install sphinx furo

# 2. Build the standalone module
DEPS=~/Workspace/omvll-v1.9.1-macos-deps
LLVM=$DEPS/LLVM-21.1.6-arm64-Darwin
PY=/opt/homebrew/opt/python@3.10

cmake -GNinja -S src -B build \
  -DOMVLL_PY_STANDALONE=1 \
  -DCMAKE_BUILD_TYPE=Release \
  -DPython3_EXECUTABLE=$PY/bin/python3.10 \
  -DPython3_INCLUDE_DIR=$PY/Frameworks/Python.framework/Versions/3.10/include/python3.10 \
  -DPython3_LIBRARY=$PY/Frameworks/Python.framework/Versions/3.10/lib/libpython3.10.dylib \
  -Dpybind11_DIR=$DEPS/share/cmake/pybind11 \
  -Dspdlog_DIR=$DEPS/lib/cmake/spdlog \
  -DLLVM_DIR=$LLVM/lib/cmake/llvm \
  -DClang_DIR=$LLVM/lib/cmake/clang
ninja -C build OMVLL                            # → build/omvll.so

# 3. Generate the HTML
OMVLL_STANDALONE_DIR=$(pwd)/build \
  /tmp/omvll-doc-venv/bin/python -m sphinx -b html doc doc/_build/html