Setup

Complete these six phases in order. Each ends with a checkpoint — do not proceed until you can confirm it.

Not sure what all these pieces are for? Read The Project Ecosystem first.

Phase 1 — Register your team

  1. Every student opens the GitHub Classroom invitation link shared by the teacher.
  2. One student creates the team using the exact teacher-defined team name.
  3. Other students search for that exact team and join it.
  4. Confirm a repository named after your team has appeared under the Estia-1a organization on GitHub.
Important

Use the exact team name given by the teacher. A wrong name creates a separate team and a separate repository — there is no way to merge them afterward.

✓ Checkpoint: Every teammate can visit github.com/Estia-1a/<your-team> and see the repository.

Phase 2 — Clone and open in VS Code

Clone with VS Code

  1. Open the command palette (Ctrl+Shift+P / Cmd+Shift+P).
  2. Run Git: Clone → Clone from GitHub.
  3. Select your team repository.
  4. Choose a local path with no accents or special characters.
  5. When VS Code asks to open the repository, click Open.
  6. When VS Code prompts to install recommended extensions, click Install All.

Clone with SmartGit (alternative)

  1. Clone the repository.
  2. Open the cloned folder in VS Code and install recommended extensions when prompted.
Warning

Windows: Keep your path short and accent-free (e.g., C:\code\pgi-2026-teamname). Accents and long paths cause compiler and CMake failures.

Required extensions (from .vscode/extensions.json):

  • GitHub Pull Requests and Issues
  • C/C++
  • CMake
  • CMake Tools

✓ Checkpoint: VS Code shows the project files and all recommended extensions are installed.

Phase 3 — Download and install libraries

Your project links against two prebuilt libraries that are not included in the repository. You must download and place them manually.

Step 1 — Identify your compiler target

Open a terminal and run:

gcc -dumpmachine

Look at the beginning of the output to choose your package:

Output starts with Download
x86_64 *-win10-mingw64.zip
i686 *-win10-mingw32.zip
Tip

Common confusion: x86_64-w64-mingw32 → download mingw64. The x86_64 prefix is the deciding factor, not the mingw32 at the end.

Step 2 — Download both packages

Get both from the v2.0.1 release:

  • estia-image-v2.0.1-win10-mingw64.zip (or mingw32)
  • getopt-v2.0.1-win10-mingw64.zip (or mingw32)

Step 3 — Extract and place correctly

Unzip each archive. Move only the inner folder directly into your project root:

✓ Correct:
your-project/
├── estia-image/
│   ├── include/
│   └── lib/
├── getopt/
│   ├── include/
│   └── lib/
└── src/

✗ Wrong (wrapper folder left inside):
your-project/
└── estia-image-v2.0.1-win10-mingw32/
    └── estia-image/
        ├── include/
        └── lib/

Do not leave zip files or wrapper folders in the project root.

✓ Checkpoint: estia-image/include/estia-image.h and getopt/include/getopt.h both exist in your project root.

Phase 4 — Validate and build

Run the validator

From the project root (use Git Bash on Windows):

bash validconfig.sh

This script checks your git config, compiler, CMake, and library presence. Fix every error it reports before continuing. It is your primary diagnostic tool throughout the project.

Tip

From VS Code: Tasks: Run Task → Estia: Validate your installation

Build and run helloworld

The project is built with CMake ToolChain. CMake needs to pick the right compiler. You can select the correct kit in VS Code (Ctrl+Shift+P → CMake: Select a Kit), or manually specify it.

Then run:

cmake -B build  -G "Unix Makefiles"
cmake --build build
./build/freud.exe -f images/input/image.jpeg -c helloworld

✓ Checkpoint: The helloworld output appears in your terminal with no errors. Every teammate repeats this on their own machine.

Phase 5 — Activate GitHub workflows (team leader only)

ImportantTeam leader only

One person does this step. Other teammates wait until the leader confirms it is done, then run git pull.

The team leader runs:

bash validconfig.sh --activate-workflows

Or from VS Code: Tasks: Run Task → Estia: Team leader activate workflows

This command:

  1. Pulls latest main.
  2. Renames disabled workflow files (*.yml.disabled) to active .yml.
  3. Creates a one-time onboarding commit and pushes to GitHub.
  4. Prints the repository Actions URL.

Everyone else: once the leader confirms the push succeeded, run:

git pull

✓ Checkpoint: Team leader confirms push succeeded. All teammates have pulled.

Phase 6 — Import issues (one person)

ImportantOne person triggers, everyone else waits

Only one teammate runs the import. Others wait for completion, then pull.

  1. Open your repository on GitHub.
  2. Go to the Actions tab.
  3. Select Import issues from Template.
  4. Click Run workflow on branch main.
  5. Wait for the green checkmark.
  6. Check the Issues tab — issues should now be visible.

Everyone else: once issues appear, run:

git pull

✓ Checkpoint: Issues are visible in the Issues tab. All teammates have pulled.

You are now ready to start coding. Go to First Steps.