Metadata-Version: 2.4
Name: starlet-setup
Version: 1.2.3
Summary: Quick setup for CMake projects
Author-email: Mason L'Etoile <masonletoile@hotmail.com>
License: MIT
Project-URL: Homepage, https://github.com/masonlet/starlet-setup
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Dynamic: license-file

# ⚠️ This Repository is Archived ⚠️

This repository has been **replaced** by [**star-setup**](https://github.com/star-setup/core), a full Rust rewrite.

## Why the change?
Python/pip feels correct for a CMake-specific tool, but with my future plans of expanding to work with multiple build systems it feels awkward to keep it as python. Rust is faster and easier to distribute, while keeping the same flow as starlet-setup.

## Quick Start with star-setup

```bash
# Homebrew (macOS/Linux)
brew install star-setup/tap/star-setup

# npm
npm install -g @star-setup/star-setup

# Shell (Linux/macOS)
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/star-setup/core/releases/latest/download/star-setup-installer.sh | sh

# PowerShell (Windows)
powershell -ExecutionPolicy Bypass -c "irm https://github.com/star-setup/core/releases/latest/download/star-setup-installer.ps1 | iex"
```

See [star-setup/core](https://github.com/star-setup/core) for full documentation.

---

# Starlet Setup
A lightweight Python utility to quickly clone, configure, and build CMake projects — from single repos to full mono-repos.

[![Tests](https://github.com/masonlet/starlet-setup/actions/workflows/ci.yml/badge.svg)](https://github.com/masonlet/starlet-setup/actions/workflows/ci.yml)
[![PyPI version](https://badge.fury.io/py/starlet-setup.svg)](https://badge.fury.io/py/starlet-setup)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
[![Python 3.6+](https://img.shields.io/badge/python-3.6%2B-blue.svg)](https://www.python.org/)

## Table of Contents
- [Features](#features)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
  - [Interactive Mode](#interactive-mode)
  - [Single Repository Mode](#single-repository-mode)
  - [Mono-Repo Mode](#mono-repository-mode)
  - [Profile Mode](#profile-mode)
  - [Config Mode](#config-mode)
- [Development](#development)
- [License](#license)

<br/>


## Quick start
```bash
pip install starlet-setup

# Interactive mode
starlet-setup

# Single-repo mode
starlet-setup username/repo
```

## Features
- **Interactive Mode**:
  - Step-by-step instructions for all configuration options
  - Shows default values for each setting
  - Skips prompts for options already set via CLI flags
  - Supports both single-repo and mono-repo workflows
  - Choose between profile or manual repository lists

- **Single Repository Mode**:
  - Clone a GitHub repository with simple `username/repo` syntax
  - Support for HTTPS (default) and SSH protocols
  - Create a dedicated build directory
  - Configure the project with CMake
  - Build the project automatically
  - Optional flags for build type, directory, cleaning, and skipping build

- **Mono-repo Mode**:
  - Clone multiple related repositories into one workspace
  - Automatically generate root CMakeLists.txt for mono-repo structure
  - Build all modules together for easy debugging and development
  - Customize which repositories to include
  - Perfect for working across multiple interdependent projects

- **Profile Mode**:
  - Save frequently used mono-repo configuration as named profiles
  - Quick access to predefined repository sets
  - Manage multiple development environments effortlessly
  - Default profile includes all core Starlet modules

- **Configurations**:
  - Save build settings as named configurations
  - Store SSH preferences, build types, and CMake arguments
  - Reuse common setups without repeating flags
  - Works with both single-repo and mono-repo modes

<br/>


## Prerequisites
- Python 3.6+
- Git
- CMake

## Installation

### From PyPI
```bash
pip install starlet-setup
```

### From GitHub
```bash
pip install git+https://github.com/masonlet/starlet-setup.git
```

Once installed, you can use the `starlet-setup` command from anywhere.   

### ⚠️ Command not found? ⚠️
<details>
<summary>If you get an error saying the command is not found, you may need to add Python's user scripts directory to your PATH.</summary>  

**Find your scripts directory**:
```bash
# Run this to find your exact scripts path
python -c "import sysconfig; print(sysconfig.get_path('scripts'))"
```

**Then add it to your PATH**:

**Linux/macOS**:
```bash
# Add to ~/.bashrc, ~/.zshrc, or equivalent
export PATH="$HOME/.local/bin:$PATH"

# Apply changes
source ~/.bashrc # or equivalent
```

**Windows (Command Prompt)**:
```cmd
# Add to PATH via System Properties > Environment Variables
# Add: %APPDATA%\Python\Scripts
```

Alternatively, you can run the script directly:
```bash
python -m starlet_setup username/repo
```
</details>

<br/>


## Configuration
Starlet Setup supports persistent configuration through a JSON file, allowing you to save your preferred defaults (e.g., SSH mode, build directory, mono-repo repositories).

### 1. Initialize Config
```bash
# Create a default configuration file in your current directory.
starlet-setup --init-config
```
This will create a `.starlet-setup.json` that can be edited to customize your setup preferences.

### 2. File Location
Starlet Setup checks for configuration files in this order:
- `./.starlet-setup.json` (current directory)
- `~/.starlet-setup.json` (home directory)

<br/>


## Usage

### <a id="interactive-mode"></a>
<details>
<summary>Interactive Mode</summary>
  
When you run `starlet-setup` without a repository argument, it automatically enters interactive mode, guiding you through all configuration options.

#### Basic Usage
```bash
# Start interactive mode
starlet-setup

# Interactive mode respects CLI flags (skips those prompts)
starlet-setup --ssh --verbose
```

#### Advanced Usage
```bash
# Pre-set mono-repo flags, interactive asks for remaining options
starlet-setup --mono-repo --ssh

# Pre-set profile, interactive asks for repo and other settings
starlet-setup --profile myprofile

# Pre-set repos, interactive asks for test repo and other settings
starlet-setup --repos user/lib1 user/lib2 --verbose

# Combine multiple flags to skip multiple prompts
starlet-setup --ssh --build-type Release --no-build
```

#### Example Session
```
Starlet Setup Interactive Mode
Enter repository (user/repo or URL): masonlet/starlet-samples
Use SSH? (y/n) [N]: y
Verbose? (y/n) [N]: 
Clean build directory if exists? (y/n) [N]: 
Selected mode: (1) Single Repo (2) Mono-Repo: 2
Mono-repo: (1) Use profile (2) Manual repo list: 1
Profile name: default
Build type [Debug]: Release
Build directory [build]: 
Additional CMake args (space separated): 
Configure only (skip build)? (y/n) [N]: 

Interactive mode complete
```

</br>
</details>


### <a id="single-repository-mode"></a>
<details>
<summary>Single Repository Mode</summary>

#### Basic Usage
  
```bash
# Clone and build a repository via HTTPS
starlet-setup username/repo
starlet-setup https://github.com/username/repo.git

# Clone and build a repository via SSH
starlet-setup username/repo --ssh
starlet-setup git@github.com:username/repo.git
```

#### Advanced Usage
```bash
# Specify build type (Debug, Release, RelWithDebInfo, MinSizeRel)
starlet-setup username/repo --build-type Release

# Specify a custom build directory
starlet-setup username/repo --build-dir my-build

# Only configure, skip building
starlet-setup username/repo --no-build

# Clean the build directory before building
starlet-setup username/repo --clean

# Show verbose output for debugging
starlet-setup username/repo --verbose

# Custom CMake args
starlet-setup username/repo --cmake-arg=-DCMAKE_CXX_COMPILER=clang++
```

<br/>
</details>


### <a id="mono-repository-mode"></a>
<details>
<summary>Mono-Repo Mode</summary>

#### BUILD_LOCAL Usage
Mono-repo mode sets `BUILD_LOCAL=ON` in the root project's CMakeLists.txt.  
This flag tells your test repository to link against local modules instead of fetching them via CMake's FetchContent:
```cmake
# In your test repo's CMakeLists.txt
if(NOT BUILD_LOCAL)
    # Fetch dependencies from GitHub
    FetchContent_Declare(starlet_engine
      GIT_REPOSITORY https://github.com/starlet-libs/engine.git
      GIT_TAG main
    )
    # ... other dependencies
endif()
```

**With mono-repo mode** (`BUILD_LOCAL=ON`):
- All modules link locally from subdirectories
- Changes in any module immediately affect your test repo
- Full debugging across module boundaries
- Single unified build for the entire ecosystem

**Without mono-repo mode** (`BUILD_LOCAL` undefined):
- Dependencies fetched via FetchContent
- Standalone builds work independently
- Users can build your repo without the full ecosystem
- Automatic dependency management

This dual-mode design allows both integrated development and standalone distribution.

#### Basic Usage
**Note:** When using `--repos` or `--profile`, mono-repo mode is automatically enabled, so the `--mono-repo` flag is optional.

```bash
# Clone and build default Starlet modules with a test repository
starlet-setup username/repo --mono-repo 

# Use SSH instead of HTTPS
starlet-setup username/repo --mono-repo --ssh

# Clone non-default repositories
starlet-setup username/repo --repos user/lib1 user/lib2
```

#### Advanced Usage
```bash
# Multiple flags
starlet-setup username/repo --mono-repo --verbose --mono-dir my-starlet

# Custom repos and multiple flags
starlet-setup username/repo --repos user/lib1 user/lib2 --ssh --verbose

# Custom CMake args
starlet-setup username/repo --mono-repo --cmake-arg=-DCMAKE_CXX_COMPILER=clang++
```

#### Default Repositories (🚀 Starlet Ecosystem)
When using mono-repo mode without `--repos` or `--profile`, the script clones repositories based on your configuration. The default profile includes:
- `starlet-libs/math`
- `starlet-libs/logger`
- `starlet-libs/controls`
- `starlet-libs/scene`
- `starlet-libs/graphics`
- `starlet-libs/serializer`
- `starlet-libs/engine`
- Your specified test repository (e.g., `masonlet/starlet-samples`)

#### Mono-Repo Structure
Mono-repo mode creates a workspace like this:
```
build-mono/
├── CMakeLists.txt   # Auto-generated root project
├── math/
├── logger/
├── controls/
├── scene/
├── graphics/
├── serializer/
├── engine/
├── starlet-samples/ # Your test repo
└── build/           # Single build output
```

This structure allows you to:
- Edit any module directory
- Build everything together
- Debug across module boundaries
- Commit changes without digging into build directories

<br/>
</details>


### <a id="profile-mode"></a>
<details>
<summary>Profile Mode (Saved Configurations)</summary>

#### Managing Profiles
```bash
# Add a new profile
starlet-setup --profile-add myprofile user/lib1 user/lib2

# List all saved profiles
starlet-setup --list-profiles

# Remove a profile
starlet-setup --profile-remove myprofile
```

#### Using Profiles
```bash
# Use the default profile
starlet-setup username/repo --profile

# Use a named profile
starlet-setup username/repo --profile myprofile

# Use a profile with SSH
starlet-setup username/repo --profile myprofile --ssh
```

<br/>
</details>


### <a id="config-mode"></a>
<details>
<summary>Config Mode (Saved Build Settings)</summary>

#### Managing Configs
```bash
# List all saved configurations
starlet-setup --list-configs

# Add a new configuration with flags
starlet-setup --config-add myconfig --ssh --build-type Release --no-build

# Remove a configuration
starlet-setup --config-remove myconfig
```

#### Using Configs
```bash
# Use a saved config
starlet-setup username/repo --config myconfig

# Override specific settings
starlet-setup username/repo --config myconfig --verbose

# Config with mono-repo mode
starlet-setup username/repo --mono-repo --config myconfig --ssh
```

</details>

<br/>


## Development

### <a id="development"></a>
<details>
<summary>Development</summary>

### Running Tests

#### 1. Clone starlet-setup
```bash
git clone https://github.com/masonlet/starlet-setup.git
cd starlet-setup
```

#### 2. Install in Development Mode
```bash
pip install -e .
```

#### 3. Run Tests
```bash
# Run all tests
pytest

# Run specific test file
pytest tests/test_config.py

# Run tests with flags
pytest -v
```
</details>

<br/>


## License
MIT License — see [LICENSE](./LICENSE) for details.
