TypePHP `--dry` Mode: Generate C++ Without Compiling

The --dry flag in TypePHP performs a dry run that generates intermediate C++ source files from your PHP code but skips the compilation and linking phases, leaving you with inspectable .cpp files in the build directory.

The swoole/typephp project is a PHP-to-C++ transpiler that compiles PHP scripts into native binaries. When you need to inspect, debug, or manually modify the generated C++ intermediate code before final compilation, the --dry mode provides a crucial stopgap that halts the pipeline immediately after code generation.

What the --dry Flag Does in TypePHP

When enabled, the --dry flag instructs the TypePHP compiler to terminate immediately after the code-generation phase. Instead of producing a final executable or shared library, the tool writes the transpiled C++ sources to your designated build directory and exits.

According to the source code in src/Translator.php, the CLI help text defines the flag at lines 90-91 as:

--dry    Dry run: only generate C++ code, skip compilation and linking

This behavior is confirmed in src/compiler.php, where a comment at line 90 explicitly states:

// --dry mode: only generate the C++ code, without compiling.

By stopping after generation, you retain full control over the C++ compilation flags, linking options, or manual source modifications.

Implementation Details

CLI Argument Parsing in src/Translator.php

The src/Translator.php file handles command-line interface definitions. Lines 90-91 register the --dry option within the help menu, ensuring users understand that enabling this parameter bypasses the native binary build phase entirely.

Compiler Execution Logic in src/compiler.php

The actual enforcement of the dry-run behavior resides in src/compiler.php. When the compiler detects the --dry flag, it exits the pipeline after invoking the code generator, never reaching the system calls that invoke the C++ compiler or linker.

Practical Usage Examples

Here are practical commands for invoking dry mode via the bin/tpc.php entry point:

Generate C++ for an entire project without compiling:

php bin/tpc.php project --dry --build-dir /tmp/typephp-build

Process a single PHP file in dry mode:

php bin/tpc.php src/MyScript.php --dry --build-dir ./tmp-build

Combine dry mode with C++ standard specification for later manual compilation:

php bin/tpc.php app.php --dry --cxx-std c++20 --build-dir ./build

In each scenario, the transpiled C++ files appear in the directory specified by --build-dir (defaulting to <project-root>/build), allowing you to inspect main.cpp and associated headers before manual or scripted compilation.

Summary

• The --dry flag generates C++ source files from PHP but stops before compilation and linking
• Implementation spans src/Translator.php (CLI help definition) and src/compiler.php (execution logic)
• Output lands in the --build-dir directory (default: ./build) as .cpp and header files
• Ideal for debugging transpiler output or integrating with custom build pipelines
• Invoked via php bin/tpc.php <source> --dry

Frequently Asked Questions

Does TypePHP --dry mode create any binary files?

No. When --dry is specified, TypePHP halts immediately after generating C++ source files. No object files, executables, or shared libraries are created; only the intermediate C++ code remains in the build directory.

Where does TypePHP place files when using --dry mode?

TypePHP writes generated C++ files to the path specified by the --build-dir argument. If omitted, files default to a build subdirectory within your project root. You can inspect these files with any text editor or external C++ toolchain.

Can I compile the C++ files generated by --dry mode manually?

Yes. The --dry mode specifically allows manual compilation workflows. After generation, you can invoke your preferred C++ compiler (such as g++ or clang++) on the generated sources with custom flags, libraries, or optimization settings not exposed through TypePHP's standard CLI.

Is --dry mode available for single files and full projects?

Yes. The flag works with any valid TypePHP input, whether passing a single PHP file (such as src/MyScript.php) or an entire project directory. The behavior remains consistent: generate C++ and stop before linking.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}