synthra 0.1.0

data/tech_docs/installation.md

@@ -0,0 +1,273 @@
+# Installation Guide
+
+Complete guide to installing and setting up FakeDataDSL in your Ruby project.
+
+## Table of Contents
+
+- [Requirements](#requirements)
+- [Installation Methods](#installation-methods)
+- [Verifying Installation](#verifying-installation)
+- [Development Installation](#development-installation)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Requirements
+
+### Minimum Requirements
+
+| Requirement | Version |
+|-------------|---------|
+| Ruby | 3.1.0 or higher |
+| Bundler | 2.0 or higher (recommended) |
+
+### Optional Dependencies
+
+| Dependency | Purpose |
+|------------|---------|
+| Faker | Automatically installed - provides realistic data |
+| Zeitwerk | Automatically installed - autoloading |
+
+---
+
+## Installation Methods
+
+### Method 1: Via Bundler (Recommended)
+
+Add FakeDataDSL to your `Gemfile`:
+
+```ruby
+# Gemfile
+
+# For production/development
+gem 'fake_data_dsl'
+
+# Or for test group only
+group :test, :development do
+  gem 'fake_data_dsl'
+end
+
+# Pin to specific version
+gem 'fake_data_dsl', '~> 1.0'
+
+# Use latest from GitHub
+gem 'fake_data_dsl', git: 'https://github.com/talaatmagdyx/fake_data_dsl.git'
+```
+
+Then install:
+
+```bash
+bundle install
+```
+
+### Method 2: Direct Installation
+
+Install via RubyGems:
+
+```bash
+gem install fake_data_dsl
+```
+
+### Method 3: From Source
+
+Clone and install from source:
+
+```bash
+# Clone repository
+git clone https://github.com/talaatmagdyx/fake_data_dsl.git
+cd fake_data_dsl
+
+# Install dependencies
+bundle install
+
+# Install gem locally
+bundle exec rake install
+
+# Or build gem manually
+gem build fake_data_dsl.gemspec
+gem install fake_data_dsl-*.gem
+```
+
+---
+
+## Verifying Installation
+
+### Check Version
+
+```ruby
+require 'fake_data_dsl'
+puts FakeDataDSL::VERSION
+# => "1.0.0"
+```
+
+### Quick Test
+
+```ruby
+require 'fake_data_dsl'
+
+# Create a simple schema
+schema = FakeDataDSL.parse(<<~DSL)
+  Test:
+    id: uuid
+    name: name
+DSL
+
+# Generate data
+data = schema.generate
+puts data
+# => {"id"=>"550e8400-e29b-41d4-a716-446655440000", "name"=>"John Smith"}
+```
+
+### CLI Test
+
+```bash
+# Check CLI is available
+fake_data_dsl --version
+
+# Generate sample data
+echo "User:
+  id: uuid
+  name: name" | fake_data_dsl generate User --stdin
+```
+
+---
+
+## Development Installation
+
+For contributing to FakeDataDSL:
+
+```bash
+# Clone the repository
+git clone https://github.com/talaatmagdyx/fake_data_dsl.git
+cd fake_data_dsl
+
+# Install development dependencies
+bundle install
+
+# Run tests to verify setup
+bundle exec rspec
+
+# Run linter
+bundle exec rubocop
+
+# Generate documentation
+bundle exec yard doc
+
+# Start console for testing
+bundle exec bin/console
+```
+
+### Development Dependencies
+
+The development environment includes:
+
+| Gem | Purpose |
+|-----|---------|
+| rspec | Testing framework |
+| rubocop | Code linting |
+| simplecov | Test coverage |
+| yard | Documentation |
+
+---
+
+## Troubleshooting
+
+### Common Installation Issues
+
+#### 1. Ruby Version Too Old
+
+```
+ERROR: fake_data_dsl requires Ruby version >= 3.1.0
+```
+
+**Solution:** Upgrade Ruby using rbenv, rvm, or asdf:
+
+```bash
+# Using rbenv
+rbenv install 3.3.0
+rbenv local 3.3.0
+
+# Using rvm
+rvm install 3.3.0
+rvm use 3.3.0
+
+# Using asdf
+asdf install ruby 3.3.0
+asdf local ruby 3.3.0
+```
+
+#### 2. Bundler Not Found
+
+```
+-bash: bundle: command not found
+```
+
+**Solution:** Install Bundler:
+
+```bash
+gem install bundler
+```
+
+#### 3. Permission Denied
+
+```
+ERROR: While executing gem ... (Gem::FilePermissionError)
+```
+
+**Solution:** Use a Ruby version manager or install with user permissions:
+
+```bash
+# Install to user directory
+gem install fake_data_dsl --user-install
+
+# Or use rbenv/rvm which doesn't require sudo
+```
+
+#### 4. OpenSSL Errors
+
+```
+SSL_connect returned=1 errno=0 state=error: certificate verify failed
+```
+
+**Solution:** Update CA certificates:
+
+```bash
+# macOS
+brew install openssl
+
+# Ubuntu/Debian
+sudo apt-get install ca-certificates
+
+# Update RubyGems
+gem update --system
+```
+
+#### 5. Native Extension Build Failures
+
+```
+ERROR: Failed to build gem native extension
+```
+
+**Solution:** Install build tools:
+
+```bash
+# macOS
+xcode-select --install
+
+# Ubuntu/Debian
+sudo apt-get install build-essential
+
+# CentOS/RHEL
+sudo yum groupinstall 'Development Tools'
+```
+
+---
+
+## Next Steps
+
+After installation:
+
+1. Read the [Quick Start Guide](quick_start.md)
+2. Explore [Basic Concepts](basic_concepts.md)
+3. Check out [Examples](../tech_example/README.md)
+