🧭 Synticore Website Compiler - Setup Guide

🧭 Overview

This guide is intentionally detailed and practical. It explains not only the commands to run, but where to run them and how to verify each step.

Synticore has two working modes:

1. GUI mode (python gui.py) for task selection and config editing.
2. Terminal mode (npm run gulp <task>) for full CLI control.

Both modes expect a valid project directory selected in config/settings.json (first item in dir_recent) or selected in the GUI.

✅ Requirements

Operating System

• Windows or Linux
• macOS code paths exist in GUI helpers, but macOS is not a primary tested platform for this repo

Required Tools

• Python 3.12+
  • requirements.txt currently targets modern package versions compatible with Python 3.12/3.13.
• Node.js 20+ + npm
  • package.json is current for Synticore v1.1.0.
• GraphicsMagick
  • Required for brand/watermark operations in image workflows.

Repo-Shipped Install Media (Current)

• Windows installers in source/setup/windows/install/:
  • python-3.13.1-amd64.exe
  • node-v22.11.0-x64.msi
• Linux Node tarball in source/setup/linux/install/:
  • node-v20.17.0-linux-x64.tar.xz

If you already have compatible versions installed globally, you can use those.

🧱 Install Steps

Windows

1. Install Python (3.12+ recommended; 3.13.1 media is included in repo).
2. Install Node.js (20+ recommended; repo media currently includes 22.11.0).
3. Ensure both are on PATH.
4. Install GraphicsMagick (global), or ensure your local tool path is available.
5. Open terminal in repo root.

Verify:

python --version
node -v
npm -v

Linux

1. Install Python (3.12+ recommended) and Tk support for GUI:

sudo apt update
sudo apt install -y python3 python3-pip python3-tk

2. Install Node.js 20+ (system package or nvm workflow).
3. Install GraphicsMagick:

sudo apt install -y graphicsmagick

4. Open terminal in repo root.

Verify:

python3 --version
node -v
npm -v

📦 Install Python And Node Dependencies

Run these commands from repository root:

pip install -r requirements.txt
npm install

What these do:

• pip install -r requirements.txt installs GUI/runtime Python dependencies.
• npm install installs Gulp pipeline dependencies listed in package.json.

Optional sanity command after install:

npm run gulp about

This checks compiler startup + project resolution behavior.

📁 Choose A Project Directory

Synticore expects a selected project folder. A valid project generally includes at least:

• config.json
• in/
• info.json (recommended; used for version display/status)

Recommended Starter Projects

• example/full
• example/min

Methods To Set Project

1. GUI method (recommended):

   • launch GUI
   • pick project from recent list or Browse

2. Manual method: edit config/settings.json:

{
  "dir_recent": [
    "./example/full",
    "./example/min"
  ],
  "dir_recent_max": 10
}

The active project is dir_recent[0].

🚀 Run The Compiler

GUI

python gui.py

Terminal

npm run gulp build

Other common commands:

npm run gulp watch
npm run gulp browser
npm run gulp plan
npm run gulp package
npm run gulp rebuild

✅ Validation Checklist

Use this after setup:

1. python --version (or python3 --version on Linux)
2. node -v
3. npm -v
4. npm run gulp about exits cleanly
5. npm run gulp build generates expected output in selected project out/
6. python gui.py launches and shows task categories/buttons

🧯 Troubleshooting

Python Not Found

• Windows: install Python and ensure PATH checkbox was enabled.
• Linux: use python3 explicitly if python alias is missing.

Node/Npm Mismatch Or Missing Modules

• Reinstall Node 20+.
• Re-run npm install at repo root.

GraphicsMagick Issues During Image Tasks

• Install/repair GraphicsMagick global installation.
• Retry with image tasks (build_image, build_brand, build_favicon).

Selected Project Rejected

• Confirm selected directory includes config.json and in/.
• Update config/settings.json dir_recent values.

Gulp Task Fails Unexpectedly

• Run npm run gulp about first to confirm baseline startup.
• Then run target task in terminal to see full logs.

🧾 Logs

Useful logs:

• _log/gui.log
• _log/gulpfile.log
• _log/setup.log (setup script related)

Read these first for stack traces, task context, and path resolution details.