Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: documentation updated #42

Merged
merged 5 commits into from
Feb 20, 2025
Merged

feat: documentation updated #42

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
b956225
fix-documentation
naman9271 Feb 1, 2025
cbd4720
Merge branch 'c2siorg:main' into fix-documentation
naman9271 Feb 16, 2025
966106d
added formating and linting docs
naman9271 Feb 16, 2025
9bedcf9
Update README.md
naman9271 Feb 20, 2025
119aee6
resolved conversations
naman9271 Feb 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
241 changes: 174 additions & 67 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,147 +1,254 @@
# GDB-UI

**GDB-UI** is a user-friendly interface built for the GNU Debugger (GDB), providing a modern web-based UI for debugging your applications. It allows developers to monitor program execution, inspect variables, set breakpoints, and more, all through an intuitive web application.
[![Build Status](https://img.shields.io/github/workflow/status/c2siorg/GDB-UI/CI/main?style=for-the-badge)](https://github.com/c2siorg/GDB-UI/actions)
[![License: MIT](https://img.shields.io/github/license/c2siorg/GDB-UI?style=for-the-badge)](LICENSE)
[![Contributions Welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=for-the-badge)](CONTRIBUTING.md)

**GitHub Repository:** [c2siorg/GDB-UI](https://github.com/c2siorg/GDB-UI)
**GDB-UI** is a modern, web-based user interface for the GNU Debugger (GDB) that enhances your debugging experience. By integrating GDB’s powerful capabilities with an intuitive design, GDB-UI simplifies the process of monitoring program execution, inspecting variables, and setting breakpoints. Perfect for developers working with C, C++, Ada, and more, our tool is designed to streamline your development workflow.

## Project Overview
**Repository:** [https://github.com/c2siorg/GDB-UI](https://github.com/c2siorg/GDB-UI)

GDB-UI simplifies the debugging process by integrating the powerful features of GDB with a sleek and easy-to-use web interface. This project is particularly useful for developers working with languages like C, C++, and Ada. The interface offers a more accessible and visual approach to debugging, making it easier to identify and fix issues in your code.
---

## Getting Started
## 🌟 Overview

### Docker Setup
GDB-UI provides an accessible interface to the robust GNU Debugger. It empowers developers by offering real-time debugging, breakpoint management, and variable inspection through an elegant web-based platform. Whether you are developing complex systems or working on small projects, GDB-UI is built to improve productivity and debugging efficiency.

The quickest way to get started with GDB-UI is by using Docker. A `docker-compose.yml` file is provided to handle the entire setup.
---

1. Ensure Docker and Docker Compose are installed on your machine.
2. Run the following command in your terminal:
## 🚀 Key Features

```sh
docker-compose up
```

This command will build and start both the frontend and backend services, making the application available at [http://localhost:3000](http://localhost:3000) (or your specified port).
- **Modern Web Interface:** Sleek and user-friendly design for ease of use.
- **Full GDB Integration:** Access the complete functionality of GDB.
- **Real-Time Debugging:** Monitor and control program execution in real time.
- **Multi-Language Support:** Ideal for C, C++, Ada, and potentially other languages.
- **Extensible Architecture:** Customize and extend the tool with plugins and additional modules.
- **Comprehensive Testing:** Frontend and backend test suites to ensure stability.
- **Docker and Manual Setup:** Multiple installation options to suit your environment.

### Manual Setup
---

If you prefer a manual setup or are unable to use Docker, follow these steps:
## 🛠 Prerequisites

#### Prerequisites
Before getting started, ensure you have the following installed:

- **Node.js:** Version 18
- **Python:** Version 3.10
- **Docker & Docker Compose:** (Optional, for containerized setup)
- **Git:** For source control management

#### Frontend Setup (React)
---

1. Navigate to the `webapp` directory:
## ⚡ Getting Started

```sh
cd webapp
```
Follow these instructions to quickly set up and begin using GDB-UI. Choose between the Docker-based or manual installation method based on your preference.

2. Install the necessary dependencies:
---

```sh
npm install
```
## 🔧 System Architecture

GDB-UI is built with a clear separation of concerns:
```
GDB-UI/
├── gdbui_server/ # Backend services
├── webapp/ # Frontend interface
```

- #### Backend (Python Server):
Handles communication with GDB, processes debugging commands, and serves APIs.
- #### Frontend (React Client):
Provides the user interface, visualizes debugging data, and interacts with the backend via REST APIs and WebSockets.

- The modular architecture ensures that both components can be developed, tested, and scaled independently.

---

## 📖 Installation

There are two primary methods to install GDB-UI: using Docker or setting up the components manually.

3. Start the development server:
---

### Server Setup

#### Docker Setup

1. **Ensure Docker and Docker Compose are installed on your machine.**
2. **Run the following command:**

```sh
npm run dev
docker-compose up
```

#### Backend Setup (Python Server)
This command builds and starts both the frontend and backend services. The application will be available at [http://localhost:3000](http://localhost:3000).

#### Manual Server Setup

1. Navigate to the `gdbui_server` directory:
1. **Navigate to the `gdbui_server` directory:**

```sh
cd gdbui_server
```

2. Install the required Python packages:
2. **Install required Python packages:**

```sh
pip install -r requirements.txt
```

3. Run the backend server:
3. **Run the backend server:**

```sh
python main.py
```

## Running Tests
---

### Frontend Tests (Vite)
### Client Setup

To run the frontend tests, follow these steps:
#### Manual Client Setup

1. Navigate to the `webapp` directory:
1. **Navigate to the `webapp` directory:**

```sh
cd webapp
```

2. Run the tests using Vite:
2. **Install the necessary dependencies:**

```sh
npm run test
npm install
```

### Backend Tests
3. **Start the client application:**

```sh
npm run dev
```

---

## ⚙️ Run in Development Mode

For a streamlined development workflow:

To run the backend tests, use the following procedure:
1. **Server:** Ensure the Python backend is running in development mode.

1. Ensure your Python environment is set up as described in the manual setup.
2. Navigate to the `gdbui_server` directory:
2. **Client:** Run the React development server with hot-reloading enabled.

3. **Live Reload:** Any changes to the code will automatically update the running application, allowing for efficient iterative development.

---

## ⚙️ Development Workflow

To maintain a high standard of code quality and collaboration, please adhere to the following development workflow guidelines.

### Branching Strategy

- **Main Branch:** Always reflects the production-ready state.

- **Feature Branches:** Create separate branches for new features or bug fixes.

- **Naming Convention:** Use clear, descriptive branch names (e.g., `feature/add-breakpoint-ui` or `bugfix/fix-variable-display`).

---

## 🔄 Testing

- **Frontend:**
Run tests using Vite. Navigate to the `webapp` directory and execute:

```sh
cd gdbui_server
cd webapp
npm run test
```

3. Run the tests using the `unittest` module:
- **Backend:**
Execute backend tests by navigating to the `gdbui_server` directory and running:

```sh
cd gdbui_server
python -m unittest discover -s tests
```

## Contributing
#### Note: Ensure that all tests pass before merging any changes.

We welcome contributions from the community! To get started:
---

1. **Fork the repository at** [c2siorg/GDB-UI](https://github.com/c2siorg/GDB-UI).
2. **Clone your fork:**
## 📈 Production Deployment

```sh
git clone https://github.com/your-username/GDB-UI.git
```
For production deployment, follow these guidelines:

3. **Create a new branch for your feature or bugfix:**
- **Docker:** Use Docker Compose to deploy a stable environment.

```sh
git checkout -b feature-name
```
- **CI/CD Pipeline:** Integrate with our CI/CD pipeline for automated testing and deployment.

4. **Make your changes and commit them:**
---

```sh
git commit -m "Description of your changes"
```
## 🛠 Linting and Formatting

5. **Push your branch to your fork:**
```
## for frontend
cd webapp
npm run lint # for check lint
npm run lint:fix # for fix lint
npm run format:check # for check format
npm run format # for fix formatting

```sh
git push origin feature-name
```

6. **Open a pull request** on the main repository.
## for backend
cd gdbui_server

make lint
make format

and if you want to do mannually

**Please ensure your code adheres to our coding standards and is thoroughly tested before submitting your pull request.**
ruff check --fix . # for Run Ruff for Linting & Auto-Fixing
flake8 . # to check the linting errors and warnig
ruff format . # Format Code with Ruff
```
---

## 🤝 Contributing

## Design
We value contributions from the community! To contribute to GDB-UI, please follow these steps:

https://www.figma.com/proto/flJ4HBaH4QhF18RSKGOWwA/GDB-UI?type=design&node-id=111-1101&t=sDAc1dWc1LAfqpaT-0&scaling=min-zoom&page-id=0%3A1&starting-point-node-id=111%3A2956
1. **Fork the repository:** https://github.com/c2siorg/GDB-UI


2. **Clone your fork:**
```
git clone https://github.com/your-username/GDB-UI.git
```
3. **Create a new branch:**
```
git checkout -b feature-or-bugfix-name
```
4. **Make your changes and write clear, descriptive commit messages.**
5. **Push your branch to your fork:**
```
git push origin feature-or-bugfix-name
```
6. **Open a pull request:** on the main repository with a detailed description of your changes.
For further details, refer to our [CONTRIBUTING.md](CONTRIBUTING.md).
---
## 📜 Resource

- Official GDB Documentation: [GDB Manual](README.md)
- React Documentation: [React Docs](https://legacy.reactjs.org/docs/getting-started.html)
- Python Documentation: [Python Docs](https://docs.python.org/3/)
- Docker Documentation: [Docker Docs](https://docs.docker.com/get-started/)
- Figma Design Prototype: [View Design](https://www.figma.com/proto/flJ4HBaH4QhF18RSKGOWwA/GDB-UI?type=design&node-id=111-1101&t=sDAc1dWc1LAfqpaT-0&scaling=min-zoom&page-id=0%3A1&starting-point-node-id=111%3A2956)

---
## 📞 Support
If you need help or have any questions, please consider the following support options:
- **GitHub Issues:** Report bugs or request features via [GitHub Issues](https://github.com/c2siorg/GDB-UI/issues).
- **Community Discussions:** Participate in discussions on our GitHub Discussions page.
---
Thank you for choosing **GDB-UI**. We hope this tool enhances your debugging workflow and accelerates your development process. Happy debugging!
#### Maintained with passion by the GDB-UI team.

---