diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..0390a4c --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,32 @@ +# Copilot Instructions + +This repository follows the DPC (Dans Plugins Community) conventions defined at +https://github.com/Dans-Plugins/dpc-conventions. Read those conventions before +making any changes. + +## Technology Stack + +- Language: C +- Compiler: gcc +- Build script: `cr.sh` (compile and run) +- Dev environment: VS Code with Dev Containers + +## Project Structure + +- `projectTemplate.c` – Main C source file +- `cr.sh` – Shell script to compile and run the project +- `.devcontainer/` – VS Code dev container configuration +- `.vscode/` – VS Code editor settings +- `.github/workflows/` – CI and release automation + +## Coding Conventions + +- Keep the template minimal and easy to understand. +- Use standard C (`stdio.h`, etc.) for maximum portability. +- Maintain the `cr.sh` script to reflect any changes to source file names or compiler flags. + +## Contribution Workflow + +- Branch from `develop` for all changes. +- Open a pull request against `develop`, not `main`. +- Reference the related GitHub issue in every pull request description. diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml new file mode 100644 index 0000000..d3e55fa --- /dev/null +++ b/.github/workflows/build.yml @@ -0,0 +1,23 @@ +name: Build + +on: + push: + branches: [ main, develop ] + pull_request: + branches: [ main, develop ] + +permissions: + contents: read + +jobs: + build: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + + - name: Compile with gcc + run: gcc projectTemplate.c -o projectTemplate.exe + + - name: Run + run: ./projectTemplate.exe diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..312d742 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,23 @@ +name: Release + +on: + release: + types: [ created ] + +permissions: + contents: write + +jobs: + build-and-attach: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + + - name: Compile with gcc + run: gcc projectTemplate.c -o projectTemplate.exe + + - name: Upload binary to release + uses: softprops/action-gh-release@v2 + with: + files: projectTemplate.exe diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..14c01d9 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,29 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). + +## [Unreleased] + +### Added + +- README.md with full project documentation +- CONTRIBUTING.md with contribution guidelines +- USER_GUIDE.md with getting-started guide +- COMMANDS.md with build and run commands reference +- CONFIG.md with configuration guide +- CHANGELOG.md +- GitHub Actions CI workflow (`.github/workflows/build.yml`) +- GitHub Actions release workflow (`.github/workflows/release.yml`) +- GitHub Copilot instructions (`.github/copilot-instructions.md`) + +## [1.0.0] – 2022-11-04 + +### Added + +- Initial C project template with "Hello World" program (`projectTemplate.c`) +- Compile-and-run script (`cr.sh`) +- VS Code dev container configuration +- VS Code editor settings +- LICENSE (Stephenson Software Non-Commercial License) diff --git a/COMMANDS.md b/COMMANDS.md new file mode 100644 index 0000000..db592b6 --- /dev/null +++ b/COMMANDS.md @@ -0,0 +1,29 @@ +# Commands Reference + +This project is a C project template. It does not provide runtime commands. Below are the build and run commands used during development. + +## Build Commands + +### Compile + +```bash +gcc projectTemplate.c -o projectTemplate.exe +``` + +**Description:** Compiles the C source file into an executable. + +### Run + +```bash +./projectTemplate.exe +``` + +**Description:** Runs the compiled executable. + +### Compile and Run + +```bash +./cr.sh +``` + +**Description:** Compiles and runs the project in one step using the provided script. diff --git a/CONFIG.md b/CONFIG.md new file mode 100644 index 0000000..e7202d6 --- /dev/null +++ b/CONFIG.md @@ -0,0 +1,43 @@ +# Configuration Guide + +This project is a minimal C project template. It does not have a runtime configuration file. + +## Dev Container Configuration + +The dev container is configured in `.devcontainer/devcontainer.json`. + +### image + +**Type:** string +**Default:** `"mcr.microsoft.com/devcontainers/base:0-jammy"` +**Description:** The Docker image used for the dev container. Defaults to an Ubuntu Jammy-based image. + +### remoteUser + +**Type:** string +**Default:** `"vscode"` +**Description:** The user account used inside the container. + +### customizations.vscode.extensions + +**Type:** array of strings +**Default:** `["GitHub.copilot"]` +**Description:** VS Code extensions that are automatically installed in the dev container. + +## VS Code Settings + +Editor settings are defined in `.vscode/settings.json`. Adjust these to match your preferences. + +## Compiler Options + +The default compile command used in `cr.sh` is: + +```bash +gcc projectTemplate.c -o projectTemplate.exe +``` + +You can customise compiler flags by editing `cr.sh` or passing additional arguments to `gcc` directly. Common options include: + +- `-Wall` – Enable all warnings +- `-g` – Include debug information +- `-O2` – Optimise for performance diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..1b05b7d --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,75 @@ +# Contributing + +## Thank You + +Thank you for your interest in contributing to C Project Template! This guide will help you get started. + +## Links + +- [Repository](https://github.com/Stephenson-Software/c-project-template) + +## Requirements + +- A GitHub account +- Git installed on your local machine +- A C compiler (e.g. `gcc`) +- A text editor or IDE + +## Getting Started + +1. [Sign up for GitHub](https://github.com/signup) if you don't have an account. +2. Fork the repository by clicking **Fork** at the top right of the repo page. +3. Clone your fork: `git clone https://github.com//c-project-template.git` +4. Open the project in your editor or IDE. +5. Compile the project: `gcc projectTemplate.c -o projectTemplate.exe` + If you encounter errors, please open an issue. + +## Identifying What to Work On + +### Issues + +Work items are tracked as [GitHub issues](https://github.com/Stephenson-Software/c-project-template/issues). + +### Milestones + +Issues are grouped into [milestones](https://github.com/Stephenson-Software/c-project-template/milestones) representing upcoming releases. + +## Making Changes + +1. Make sure an issue exists for the work. If not, create one. +2. Switch to `develop`: `git checkout develop` +3. Create a branch: `git checkout -b ` +4. Make your changes. +5. Test your changes. +6. Commit: `git commit -m "Description of changes"` +7. Push: `git push origin ` +8. Open a pull request against `develop`, link the related issue with `#`. +9. Address review feedback. + +## Testing + +Compile and run the project to verify your changes: + +Linux / macOS: + +```bash +gcc projectTemplate.c -o projectTemplate.exe +./projectTemplate.exe +``` + +Windows (with MinGW or similar): + +```bat +gcc projectTemplate.c -o projectTemplate.exe +projectTemplate.exe +``` + +You can also use the provided compile-and-run script: + +```bash +./cr.sh +``` + +## Questions + +Open a GitHub Discussion or issue in this repository. diff --git a/README.md b/README.md index 3691865..62dd835 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,100 @@ -# C Project Template -This is a template for a C project. +# C Project Template + +## Description + +C Project Template is a minimal template for starting new C projects. It provides a simple "Hello World" program, a compile-and-run script, and a VS Code dev container configuration to get you up and running quickly. + +## Installation + +1. Click **Use this template** on the [GitHub repository page](https://github.com/Stephenson-Software/c-project-template) to create a new repository from this template, or clone it directly: + ``` + git clone https://github.com/Stephenson-Software/c-project-template.git + ``` +2. Ensure you have `gcc` installed on your system. +3. Compile the project: + ``` + gcc projectTemplate.c -o projectTemplate.exe + ``` +4. Run the compiled program: + ``` + ./projectTemplate.exe + ``` + +## Usage + +### Documentation + +- [User Guide](USER_GUIDE.md) – Getting started and common scenarios +- [Commands Reference](COMMANDS.md) – Build and run commands +- [Configuration Guide](CONFIG.md) – Project configuration options + +## Support + +### Experiencing a bug? + +Please fill out a bug report [here](https://github.com/Stephenson-Software/c-project-template/issues/new). + +- [Known Bugs](https://github.com/Stephenson-Software/c-project-template/issues?q=is%3Aissue+is%3Aopen+label%3Abug) + +## Contributing + +- [CONTRIBUTING.md](CONTRIBUTING.md) + +## Testing + +### Building and Running + +Linux / macOS: + +```bash +gcc projectTemplate.c -o projectTemplate.exe +./projectTemplate.exe +``` + +Windows (with MinGW or similar): + +```bat +gcc projectTemplate.c -o projectTemplate.exe +projectTemplate.exe +``` + +If you see `Hello World!` printed to the console, the build was successful. + +## Development + +### Dev Container + +A VS Code dev container is provided for development. + +#### Setup + +1. Install [Docker Desktop](https://www.docker.com/products/docker-desktop) and [VS Code](https://code.visualstudio.com/). +2. Install the [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension. +3. Open the repository in VS Code. +4. When prompted, click **Reopen in Container** (or run the command **Dev Containers: Reopen in Container**). + +#### Compile and Run Script + +Use the provided `cr.sh` script to compile and run in one step: + +```bash +./cr.sh +``` + +## Authors and Acknowledgement + +### Developers + +| Name | Main Contributions | +|------|--------------------| +| Daniel McCoy Stephenson | Creator and maintainer | + +## License + +This project is licensed under the [Stephenson Software Non-Commercial License (Stephenson-NC)](LICENSE). + +See the [LICENSE](LICENSE) file for full details. + +## Project Status + +This project is in active development as a template for new C projects. diff --git a/USER_GUIDE.md b/USER_GUIDE.md new file mode 100644 index 0000000..1bdff84 --- /dev/null +++ b/USER_GUIDE.md @@ -0,0 +1,58 @@ +# User Guide + +## Prerequisites + +- A C compiler such as `gcc` +- Git (to clone the repository or use it as a template) + +## First Steps + +1. Create a new repository from this template by clicking **Use this template** on the [GitHub repository page](https://github.com/Stephenson-Software/c-project-template), or clone it directly: + ``` + git clone https://github.com/Stephenson-Software/c-project-template.git + ``` +2. Open the project in your editor or IDE. + +## Common Scenarios + +### Compiling and Running + +Compile the project with `gcc`: + +```bash +gcc projectTemplate.c -o projectTemplate.exe +``` + +Run the compiled program: + +```bash +./projectTemplate.exe +``` + +You should see the following output: + +``` +Hello World! +``` + +### Using the Compile-and-Run Script + +A convenience script (`cr.sh`) is provided that compiles and runs the project in one step: + +```bash +./cr.sh +``` + +### Using the Dev Container + +If you use VS Code, you can develop inside a pre-configured container: + +1. Install [Docker Desktop](https://www.docker.com/products/docker-desktop) and [VS Code](https://code.visualstudio.com/). +2. Install the [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension. +3. Open the repository in VS Code and reopen in the container when prompted. + +### Customising the Template + +- Rename `projectTemplate.c` to match your project name. +- Update the `cr.sh` script to reflect the new file name. +- Modify the code in the `main()` function to begin building your application.