Project Setup Guide

Prerequisites

Before starting, ensure you have the following installed:

• Xcode 15.0+: Latest version with iOS 16.0+ support
• macOS 12.0+: Required for Xcode and development tools
• Git: For version control
• Make: Command-line tool (usually pre-installed on macOS)

Quick Setup (Recommended)

One-Command Setup

make dev

This single command will:

1. ✅ Install Tuist (if not already installed)
2. 🧹 Clean any previous cache
3. 📦 Generate all modules and workspace
4. 🚀 Open the project in Xcode

Verify Installation

After running make dev, you should see:

• Xcode opens with SmartShop.xcworkspace
• Project builds successfully
• All modules are visible in the project navigator

Manual Setup

If you prefer to run commands individually:

1. Install Tuist

# Install Tuist using the official installer
curl -Ls https://install.tuist.io | bash

# Or using Homebrew
brew install tuist

# Verify installation
tuist --help

2. Clone and Setup Project

# Clone the repository
git clone https://github.com/your-username/SmartShop.git
cd SmartShop

# Install Tuist (if not installed globally)
make install

# Generate the project
make generate

# Open in Xcode
make open

Project Structure After Setup

After successful setup, you'll have:

SmartShop/
├── SmartShop.xcworkspace          # Main workspace (generated)
├── Modules/
│   ├── App/
│   │   ├── App.xcodeproj          # Generated app project
│   │   └── Core/AppDelegate.swift
│   ├── uHome/
│   │   ├── Home.xcodeproj         # Generated Home project
│   │   ├── Interface/Sources/
│   │   └── Implementation/Sources/
│   └── uNetwork/
│       ├── Network.xcodeproj      # Generated Network project
│       ├── Interface/Sources/
│       └── Implementation/Sources/
├── Tuist/
│   └── ProjectDescriptionHelpers/
├── Makefile
└── Workspace.swift

Available Commands

Development Commands

make dev              # Complete setup: install + generate + open
make generate         # Generate all projects and workspace
make open            # Open workspace in Xcode
make build           # Build the entire project
make test            # Run all tests

Maintenance Commands

make clean           # Clean Tuist cache
make clean-all       # Remove all generated files and cache
make status          # Check project status
make help            # Show all available commands

Troubleshooting

Common Issues

1. Tuist Not Found

# Error: command not found: tuist
# Solution: Install Tuist
curl -Ls https://install.tuist.io | bash
source ~/.zshrc  # or ~/.bash_profile

2. Permission Denied

# Error: Permission denied
# Solution: Fix permissions
chmod +x Makefile
sudo xcode-select --install

3. Xcode Command Line Tools Missing

# Error: xcode-select: error: tool 'xcodebuild' requires Xcode
# Solution: Install Xcode Command Line Tools
xcode-select --install

4. Cache Issues

# Error: Build failures or stale cache
# Solution: Clean everything
make clean-all
make generate

5. Dependency Resolution Issues

# Error: Module not found or dependency issues
# Solution: Clean and regenerate
tuist clean
tuist generate --no-open

Verification Steps

1. Check Tuist Installation

tuist --version
# Expected output: 4.x.x or later

2. Verify Project Generation

make status
# Expected output:
#   📊 Project status:
#   - Tuist installed: ✅
#   - Project generated: ✅
#   - Modules:
#     - uHome: ✅
#     - uNetwork: ✅

3. Test Build

make build
# Should complete without errors

4. Run Tests

make test
# All tests should pass

Development Workflow

Daily Development

# Start of day
make dev

# After changes to Project.swift files
make generate

# Before committing
make test
make build

Adding New Dependencies

1. Update the relevant Project.swift file
2. Run make generate to update projects
3. Open workspace and verify new dependencies

Working with Multiple Modules

1. Each module has its own Xcode project
2. The workspace combines all modules
3. Build and test individual modules independently
4. Use the workspace for integration testing

IDE Configuration

Xcode Settings

After opening the workspace, configure Xcode:

1. Build System

• Xcode → Preferences → Locations
• Ensure Command Line Tools points to current Xcode

2. Source Control

• Xcode → Preferences → Source Control
• Enable source control for better Git integration

3. Text Editing

• Xcode → Preferences → Text Editing
• Enable line numbers, code folding, and syntax highlighting

Recommended Xcode Extensions

• SwiftLint: Code style enforcement
• SwiftFormat: Automatic code formatting
• Tuist Plugin: Enhanced Tuist integration (if available)

CI/CD Setup

Local Testing Before Push

# Run the same checks as CI
make install
make generate
make build
make test

GitHub Actions Integration

The project includes CI/CD configuration. See Continuous Integration for details.

Environment Variables

Optional Configuration

# Set in ~/.zshrc or ~/.bash_profile

# Tuist cache directory (optional)
export TUIST_CACHE_PATH="$HOME/.tuist-cache"

# Xcode developer directory (if multiple Xcode versions)
export DEVELOPER_DIR="/Applications/Xcode.app/Contents/Developer"

Performance Optimization

Build Performance

# Use Tuist caching
tuist cache warm

# Parallel builds (automatic with workspace)
# Individual module builds are parallelized

Development Performance

• Use selective builds when working on specific modules
• Leverage Tuist's caching for faster generation
• Keep dependencies minimal and focused

Next Steps

After successful setup:

1. 📖 Read uFeature Concept to understand the architecture
2. 🏗️ Explore Modular Architecture for implementation details
3. 🧪 Learn about Testing Strategy for quality assurance
4. ⚡ Familiarize yourself with Makefile Automation

Getting Help

Resources

• 📚 Tuist Documentation
• 💬 Tuist Community Slack
• 🐛 Project Issues

Contact

• 👤 Author: Narlei Moreira
• 📧 Project questions welcome on LinkedIn

---

Next: Makefile Automation