From fa7e738b7eade5a627218741a6fb4bd1617f7801 Mon Sep 17 00:00:00 2001
From: "Max P." <Mail@MPassarello.de>
Date: Thu, 1 May 2025 17:43:12 +0200
Subject: [PATCH] docs(readme): expand README with detailed usage and setup

- Add comprehensive overview of HDLBuild features and functionality
- Include installation prerequisites and step-by-step instructions
- Document CLI commands with examples for common tasks
- Provide example `project.yml` configuration for customization
- Add sections on contributing, license, and GitHub Actions
- Enhance clarity and usability for new users and contributors

Signed-off-by: Max P. <Mail@MPassarello.de>
---
 README.md | 168 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 167 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 28a6f8d..a92e32a 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,168 @@
-# hdlbuild
+# HDLBuild
 
+HDLBuild is a flexible build management tool for FPGA projects. It simplifies the process of managing dependencies, building, testing, and deploying FPGA designs using Xilinx ISE tools.
+
+## Features
+
+- **Dependency Management**: Automatically resolves and manages project dependencies from Git repositories.
+- **Build Automation**: Supports synthesis, implementation, and bitstream generation for FPGA designs.
+- **Testbench Execution**: Automates the process of building and running testbenches.
+- **Customizable Tool Options**: Provides extensive configuration options for Xilinx ISE tools.
+- **Project Initialization**: Quickly set up new projects with predefined templates.
+- **Rich Console Output**: Provides detailed and interactive console feedback using `rich`.
+
+---
+
+## Installation
+
+### Prerequisites
+
+- Python 3.10 or higher
+- Poetry (for dependency management)
+- Xilinx ISE (14.7) installed and configured
+
+### Steps
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/your-repo/hdlbuild.git
+   cd hdlbuild
+   ```
+
+2. Install dependencies:
+   ```bash
+   poetry install
+   ```
+
+3. Add the `hdlbuild` CLI to your PATH:
+   ```bash
+   poetry shell
+   ```
+
+---
+
+## Usage
+
+### CLI Commands
+
+HDLBuild provides a command-line interface (CLI) for managing FPGA projects. Below are the available commands:
+
+#### 1. **Initialize a New Project**
+   ```bash
+   hdlbuild init
+   ```
+   - Creates a new project with a project.yml configuration file and a .gitignore file.
+
+#### 2. **Resolve Dependencies**
+   ```bash
+   hdlbuild dep
+   ```
+   - Clones and resolves all project dependencies defined in project.yml.
+
+#### 3. **Build the Project**
+   ```bash
+   hdlbuild build
+   ```
+   - Runs the full build process, including synthesis, implementation, and bitstream generation.
+
+   - To only synthesize the design:
+     ```bash
+     hdlbuild build synth
+     ```
+
+#### 4. **Run Testbenches**
+   ```bash
+   hdlbuild test <testbench_name>
+   ```
+   - Builds and runs the specified testbench.
+
+#### 5. **Clean Build Artifacts**
+   ```bash
+   hdlbuild clean
+   ```
+   - Removes build artifacts.
+
+   - To clean all generated files:
+     ```bash
+     hdlbuild clean all
+     ```
+
+---
+
+## Configuration
+
+The project is configured using a project.yml file. Below is an example configuration:
+
+```yml
+name: MyFPGAProject
+topmodule: top_module
+target_device: xc3s1200e-4-fg320
+xilinx_path: /opt/Xilinx/14.7/ISE_DS/ISE
+
+constraints: constraints.ucf
+
+sources:
+  vhdl:
+    - path: src/*.vhd
+      library: work
+
+testbenches:
+  vhdl:
+    - path: tests/*.vhd
+      library: work
+
+dependencies:
+  - git: "https://github.com/example/dependency.git"
+    rev: "main"
+
+build:
+  build_dir: working
+  report_dir: reports
+  copy_target_dir: output
+
+tool_options:
+  xst:
+    - "-opt_mode Speed"
+    - "-opt_level 2"
+  map:
+    - "-detail"
+    - "-timing"
+  par: []
+  bitgen:
+    - "-g StartupClk:JtagClk"
+```
+
+---
+
+## Development
+
+### Building the Package
+
+To build the Python package:
+```bash
+poetry build
+```
+
+---
+
+## GitHub Actions
+
+The project includes GitHub workflows for building and deploying the package:
+
+1. **Build and Publish**: build-and-deploy.yml
+
+---
+
+## License
+
+This project is licensed under the MIT License.
+
+---
+
+## Contributing
+
+Contributions are welcome! Please follow these steps:
+
+1. Fork the repository.
+2. Create a new branch for your feature or bugfix.
+3. Submit a pull request.