GETTING STARTED

Build PCFC11 from source

Build the bundled PCFC11 0.2.27 compiler once with your local Python and GCC tools. PyCForge keeps it in a fixed location and checks the recorded build before use.

Requirements

The PyCForge application supports Python 3.11–3.13. The standalone compiler build and tests need no third-party Python packages. PCFC11 emits x86-64 code for these two hosts; macOS, ARM64 and 32-bit hosts are outside this bundled compiler's supported route. Other C Compilers remains available for its supported targets.

PCFC11 parses and compiles C itself; GCC supplies assembly, linking and system runtime support. Keep the complete GCC installation. A lone gcc.exe copied without its supporting files is insufficient. PyCForge supplies no installers, downloads no tools, and never builds PCFC11 at startup. Missing PCFC11 does not prevent editing or transpilation.

Guided setup

1. Click the copper Compile button when PCFC11 is missing or changed. Setup is available before transpilation. Transpile → Build PCFC11… opens setup at any time.
2. In Python executable, select a native 64-bit Python 3.11+ executable. In GCC executable, select the complete native toolchain's driver. Windows commonly uses C:\msys64\ucrt64\bin\gcc.exe; Linux commonly uses /usr/bin/gcc. Browse selects a file without executing it.
3. Review the read-only Managed compiler path. PyCForge chooses this location; no destination chooser is provided. Adjust Build timeout if necessary; it defaults to 300 seconds and accepts 30–1200 seconds for the compiler build step. Prerequisite, identity and smoke checks have separate short limits.
4. Choose Build PCFC11. The dialog checks tools, extracts the verified bundled source, builds PCFC11, checks its identity, and compiles and runs small verification programs at O0 and O1. The log remains visible while the workspace stays responsive. Cancel Build stops the operation.
5. When ready, use Continue to Compile if current generated C is available, or close setup and transpile first. Successful tool paths are remembered. Recheck verifies an existing build; Rebuild PCFC11 explicitly rebuilds it. Copy Report copies status, paths and the current log.

A failed or canceled rebuild preserves the previous compiler. Recheck can confirm that retained build. Closing setup or the workspace during a build requests cancellation and waits for the worker to finish. Builds and program compilation share a lock across PyCForge windows; a busy compiler reports that another operation must finish first.

Fixed location and startup verification

The managed slot is independent of the pip installation folder, virtual environment and working directory. This avoids requiring write access to site-packages and keeps the compiler available across PyCForge upgrades that bundle the same source. Its path includes the compiler release, source fingerprint and native target:

The setup dialog shows the exact path for your account. Keep the compiler source, adjacent headers and build record together. The current folder contains build.json and build.log; a successful rebuild retains the replaced folder as previous. Publication is protected by a lock and rollback. If interruption leaves only a recorded previous build, the next check can restore it.

Normal startup compares SHA-256 content fingerprints for the executable, bundled source/build inputs, headers and saved GCC driver. It then runs a bounded compiler identity probe for name, release, target and process interface. Compile repeats verification before use. A small copper loading panel appears while this check runs; Cancel dismisses the request without opening a compile or setup dialog. The original code-bracket PyCForge icon identifies these compiler dialogs. A changed executable is refused before its identity command is run. A saved timestamp alone is never enough. Missing files or failed checks lead to setup, not an automatic rebuild. Recovery startup defers this optional compiler probe.

These checks establish continuity with the locally recorded build. They are not a publisher digital signature, a full toolchain attestation or proof of compiler correctness. Replacing both files and their local record is outside that guarantee. GCC helper programs, libraries and DLLs must remain compatible; their availability is checked by actual build/use, not by recursively hashing the entire toolchain. Moving or updating the saved GCC driver requires rebuilding PCFC11.

When a later PyCForge release bundles different compiler source, it gets a separate slot. Existing slots and separately extracted source folders are not removed by a pip uninstall. Use the displayed location when reviewing disk usage; close PyCForge before manually removing an obsolete slot.

Compile your program

1. Transpile the current Python source bundle in Typed or Runtime mode.
2. Choose Compile beside Transpile, or Transpile → Compile with PCFC11… (Ctrl+Shift+Return).
3. The verified PCFC11 executable, saved GCC assembler/linker and native target are already filled in and read-only. Choose object or executable output, your program's output filename, and O0 or O1. Program output cannot overwrite the managed compiler folder.
4. An executable needs a no-argument entry function: Typed returns int; Runtime returns int or None. A function named start is a useful entry. Use object output for functions called by another C program.
5. Choose Compile in the dialog and review the log and diagnostics. Copy Report preserves compiler identity, commands and result. Build PCFC11 from source… opens compiler setup.

Build children receive the selected backend directory in PATH without modifying the application or system environment. Editing a participating source cancels an outdated program build; failure or cancellation preserves previous output. Program compilation never runs your program. Setup runs only its own small verification programs. PCFC11 remains separate from Transpile → Other C Compilers…, which retains GCC, Clang, MSVC and Clang-cl.

Generated Runtime C includes its value routines and does not need Python to execute on a compatible host. Compiler setup does not alter the Runtime memory and collection contract; active collection remains opt-in.

An independent source copy

For compiler experiments and the original standalone test workflow, extract a separate working copy using the Python environment containing PyCForge, or run from the PyCForge source root:

python -m pycforge.pcfc11 --extract ./compilers

Windows can use py -m pycforge.pcfc11 --extract .\compilers. Extraction verifies the bundled archive's SHA-256, creates compilers/PCFC11-0.2.27 with complete source, headers, licenses and tests, and never executes them. It refuses to merge with an existing folder; choose another parent to make another copy.

The original archive is also present at pycforge/pcfc11/PCFC11-0.2.27-source.zip in the source distribution. Its provenance record identifies the exact release. Historical plans in that unchanged archive do not replace this manual. The managed IDE route always builds its own pinned copy; use the command-line build service below for a separately built compiler.

Manual Windows build

Install MSYS2 and UCRT64 GCC separately using MSYS2's instructions. The UCRT64 package is mingw-w64-ucrt-x86_64-gcc. From PowerShell, adjust your MSYS2 path as needed:

cd .\compilers\PCFC11-0.2.27
$env:Path = "C:\msys64\ucrt64\bin;$env:Path"
py tools\build.py --cc "C:\msys64\ucrt64\bin\gcc.exe"
.\pcfc11.exe --version
.\pcfc11.exe -std=c11 -O1 examples\hello.c -o hello.exe
.\hello.exe

The PATH assignment applies to this PowerShell session and its children. It makes matching DLLs and helpers available for manual commands. The last command explicitly runs the smoke program. Keep pcfc11.exe beside its entire matching include directory. WSL builds the Linux compiler, not the native Windows compiler.

Manual Linux build

cd compilers/PCFC11-0.2.27
python tools/build.py --cc /usr/bin/gcc
./pcfc11 --version
./pcfc11 -std=c11 -O1 examples/hello.c -o hello
./hello

Substitute python3 and your GCC path if needed. Keep pcfc11 beside its matching include directory. These source builds need no administrator privileges once prerequisite tools are available.

For app.py containing def start() -> int: return 0, an explicit external-compiler invocation on Windows is:

py -m pycforge.build app.py --entry main.start --compiler-family pcfc11 --compiler "C:\path\PCFC11-0.2.27\pcfc11.exe" --toolchain "C:\msys64\ucrt64\bin\gcc.exe" --output program.exe

On Linux use python, native paths and output such as program. Add --runtime-values for Runtime conversion or --kind object for object output. This explicit command-line route is separate from the IDE's fixed managed slot.

Standalone compiler tests

Run the existing workflow in an independently extracted copy:

bash test-pcfc11.sh

On Windows use MSYS2 UCRT64 or Git Bash with native Windows Python 3.11+. The PowerShell alternative is:

py tools\test_windows.py --cc "C:\msys64\ucrt64\bin\gcc.exe"

The suite rebuilds the compiler and writes logs and a results ZIP under test-results. Running it inside the managed folder would replace the recorded executable and require setup again. Retain the results ZIP even on failure. OpenBLAS and LAPACKE are optional extra qualification, not basic prerequisites. Bundled PyCForge fixtures are historical inputs; test current application programs too. PyCForge's source distribution retains test-windows-gc.ps1 and WINDOWS-GC-TESTING.md for current generated-memory checks.

Troubleshooting