Skip to content

Quick Start

Jump to bottom
PCART Bot edited this page Sep 17, 2026 · 7 revisions

Quick Start Guide

Get started with PCART in 5 minutes.

Prerequisites

PCART Runtime Environment

  • Linux (Ubuntu 18.04.1+) or Windows 11
  • Python 3.9
  • dill 0.3.7

Target Project Environments

  • Python 3.x
  • dill 0.3.7
  • The library you want to upgrade (at current and target versions)
  • Project’s requirements.txt

Step 1: Install PCART

git clone https://github.com/PCART-tools/PCART.git
cd PCART
python -m pip install -r requirements.txt

PCResolve is optional. When installed, it provides cross-file symbol tracing during API-call discovery; otherwise PCART automatically uses its built-in extractor.

python -m pip install "pcresolve>=1.0.4"

Step 2: Prepare Project Environments

Create two virtual environments for your target project:

# Create environments with current and target versions
conda create -n myproject_v1 python=3.x
conda create -n myproject_v2 python=3.x

# Activate current version environment
conda activate myproject_v1
pip install dill==0.3.7
pip install -r /path/to/your/project/requirements.txt
pip install your-library==1.7.1

# Activate target version environment
conda deactivate
conda activate myproject_v2
pip install dill==0.3.7
pip install -r /path/to/your/project/requirements.txt
pip install your-library==1.9.0

Step 3: Create Configuration File

You may create the JSON file in Configure/ or elsewhere. Both main.py and extractLibAPI.py accept an absolute path, an existing path relative to the current working directory, or a bare file name that is looked up under Configure/.

The runCommand field supports multiple formats:

  • python run.py — standard Python script
  • python3 src/main.py — Linux python3
  • py -3.9 train.py — Windows py launcher
  • pytest tests/ or python -m pytest tests/ — console scripts / module execution

PCART auto-detects the Python executable from your currentEnv/targetEnv. See the Configuration-Guide for all supported formats.

Linux:

{
  "projPath": "/home/user/myproject",
  "runCommand": "python run.py",
  "runFilePath": "",
  "libName": "torch",
  "currentVersion": "1.7.1",
  "targetVersion": "1.9.0",
  "currentEnv": "/home/user/anaconda3/envs/myproject_v1",
  "targetEnv": "/home/user/anaconda3/envs/myproject_v2"
}

Windows:

{
  "projPath": "C:\\Users\\user\\myproject",
  "runCommand": "python run.py",
  "runFilePath": "",
  "libName": "torch",
  "currentVersion": "1.7.1",
  "targetVersion": "1.9.0",
  "currentEnv": "C:\\Users\\user\\anaconda3\\envs\\myproject_v1",
  "targetEnv": "C:\\Users\\user\\anaconda3\\envs\\myproject_v2"
}

Relative values for projPath, currentEnv, and targetEnv are resolved from the PCART repository root. runFilePath is always relative to projPath and identifies the entry file's directory; it does not limit which project files are analyzed.

Step 4: Extract Definitions and Run PCART

# If API definitions are missing, extract them first
python extractLibAPI.py -cfg myproject.json

# Run detection and repair
python main.py -cfg myproject.json

# Optionally generate repair patches and a repaired project copy
python main.py -cfg myproject.json --write-patch

# Optionally remove a successful run workspace after report export
python main.py -cfg myproject.json --clean-workspace

# Optionally combine patch output with workspace cleanup
python main.py -cfg myproject.json --write-patch --clean-workspace

Patch output is disabled by default. Enabling --write-patch does not change repair logic or modify the original project.

PCART instruments a copy of your project and runs runCommand in currentEnv to generate pkl files. These pkls capture runtime API call data and are used for dynamic API signature matching. Make sure the command exercises the API calls you want to check: discovered calls that are not executed are reported with Coverage: No and are not compatibility-analyzed. See How-It-Works for details on the pkl lifecycle.

Step 5: View Results

Repair reports are saved to Report/runs/{run_id}/{command_id}/ — each completed analysis produces an isolated output directory with the repair report.

With --write-patch, applicable repair patches are also exported under patches/. A project copy containing only Successful repairs is exported under fixed_project/{project}/ when there are applicable Successful edits. The original project remains unchanged. See How-It-Works for the output structure and generation rules.

Intermediate workspaces are kept under PCARTRuns/runs/ by default. --clean-workspace removes only a successful run workspace after its report has been exported; failed workspaces and all exported outputs, including patches and repaired project copies, are retained.

Next Steps

Clone this wiki locally