-
Notifications
You must be signed in to change notification settings - Fork 13
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #42 from naman9271/fix-documentation
feat: documentation updated
- Loading branch information
Showing
1 changed file
with
174 additions
and
67 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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. | ||
| [](https://github.com/c2siorg/GDB-UI/actions) | ||
| [](LICENSE) | ||
| [](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. | ||
| --- |