https://github.com/cjdb/new_cxx_project
A tool that generates a new C++ project structure so you can start writing your project immediately
https://github.com/cjdb/new_cxx_project
Last synced: about 1 year ago
JSON representation
A tool that generates a new C++ project structure so you can start writing your project immediately
- Host: GitHub
- URL: https://github.com/cjdb/new_cxx_project
- Owner: cjdb
- License: other
- Created: 2024-07-31T03:27:53.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-08-24T19:44:30.000Z (almost 2 years ago)
- Last Synced: 2025-03-24T10:06:56.329Z (over 1 year ago)
- Language: CMake
- Size: 342 KB
- Stars: 10
- Watchers: 2
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# new_cxx_project
Welcome to new_cxx_project! This is a project template generator for C++ projects. Its primary
purpose is to reduce the amount of boilerplate that you need to interact with in order to get started
with your project.
You can read a better version of the docs at https://new-cxx-project.readthedocs.io.
```{toctree}
:maxdepth: 1
LICENCE
CODE_OF_CONDUCT
source/generated_files/cmake
source/generated_files/vcpkg
```
## Generated files
new_cxx_project currently generates a project with support for the following tools:
* Git
* GitHub (optional)
* [Sphinx](https://https://www.sphinx-doc.org) (a documentation tool)
* CMake
* [vcpkg](https://vcpkg.io) (a C++ package manager, optional)
### Git
By default, the project will start with a single commit, containing all of the generated files.
### GitHub
If the project's remote either starts with `https://github.com/` or `git@github.com:`, then the
project will contain files for opening pull requests, bug reports, feature requests, and a GitHub
Action for [continuous integration](https://en.wikipedia.org/wiki/Continuous_integration).
### Sphinx
Sphinx is a documentation tool. We generate a `docs` directory that is built alongside your project.
Sphinx supports both [Markdown](https://mystmd.org) and [reStructured Text](https://docutils.sourceforge.io/rst.html).
The readme, licence, and code of conduct files are all drafted in Markdown, but your other files can
be written in reStructured Text.
### CMake
new_cxx_project largely exists to generate CMake files that you need to write (but probably don't)
want to. The CMake library that's generated is intended to simplify your development process, so that
you spend less time writing CMake, and more time working on your project.
:::{seealso}
:::
### vcpkg
new_cxx_project can optionally support for vcpkg. This includes adding it as a submodule, adjusting
the CMake components to support vcpkg, and the documentation.
:::{seealso}
:::
## Getting started
### Prerequisites
new_cxx_project has a few dependencies in order to be run. The best way to install these is to run
`install_prerequisites.py`, found in the top-level directory of this repo. The only prerequisite to
run that is Python 3.
You'll also need either a full LLVM toolchain or a full GNU toolchain, if you plan to use the toolchain
files that ship with the project by default.
### Generating a project
1. This project is fairly straightforward to use. Most projects can probably get away with running the
following:
```sh
$ ${HOME}/.config/new_cxx_project/bin/python new_cxx_project.py /tmp/hello_world --author='Your name'
```
This generates a project called `hello_world` in `/tmp/hello_world`.
2. Create a file called `/tmp/hello_world/source/hello.cpp`:
```cpp
#include
int main()
{
std::println("Hello, world!");
}
```
3. Edit `/tmp/hello_world/source/CMakeLists.txt`:
```cmake
cxx_executable(
TARGET hello
SOURCES hello.cpp
)
```
4. Run `cd /tmp/hello_world`.
5. Run `export PATH="${HOME}/.config/new_cxx_project/bin:${PATH}"`.
6. Run **one** of the following:
```sh
# If you have the LLVM toolchain installed (Clang, libc++, and friends)
$ cmake -GNinja -S. -Bbuild -DCMAKE_BUILD_TYPE=Debug -DCMAKE_TOOLCHAIN_FILE="$PWD/config/cmake/toolchains/x86_64-linux-unknown-llvm.cmake"
```
```sh
# If you have the GNU toolchain installed (GCC and friends)
$ cmake -GNinja -S. -Bbuild -DCMAKE_BUILD_TYPE=Debug -DCMAKE_TOOLCHAIN_FILE="$PWD/config/cmake/toolchains/x86_64-linux-unknown-gnu.cmake"
```
7. Now run `ninja -C build`.
8. Finally, run `build/source/hello`. You should see `Hello, world!` output to screen.
9. Congrats! That's your first project done :)
## Options
* `--remote=` sets the Git remote. If the tool detects a valid GitHub remote, then it will
also generate files for tracking issues, pull requests, and GitHub actions.
* `--package-manager=` sets the project's package manager. Valid values are `none` and `vcpkg`.
Defaults to `none`.
* `--package-manager-remote=` sets the remote to download the package manager from. Remotes
that are on-disk should be prefixed with `file://`. The default remotes are
* **vcpkg**: https://github.com/Microsoft/vcpkg.git
## Can you also support <feature>?
Contributions to the project are welcome! Supporting other toolchains, CMake features, build systems,
package managers, and remotes are certainly things that I'd like to see added. Please open a [feature
request](https://github.com/cjdb/new_cxx_project/issues/new?assignees=&labels=enhancement&projects=&template=feature_request.yml&title=%3CAdd+a+descriptive+title+here%3E)
to discuss your needs.
In particular, help with supporting MSVC and delivering updates to previously-generated projects
would be appreciated.
## Can I change the licence for the files I generate?
Sorry, no. This project has multiple contributors, and to relicencing would require getting permission
from each contributor, for each licence. Also, in order to simplify the process for developers working
on different projects generated by `new_cxx_project.py` with different owners, we intend to keep the
licencing story very simple.
The generated source code and generated documentation have different (but still really permissive) licences.
Source code is licenced under [Apache Licence, Version 2.0 with LLVM Exceptions](https://llvm.org/LICENSE.txt).
The documentation is licenced under [Creative Commons Attribution-ShareAlike 4.0 International](https://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)
(CC BY-SA 4.0).
## Can I edit the generated files?
Yes! You can and should edit them as you see fit. Any changes that you make are owned by you.
## Indices and tables
* {ref}`genindex`
* {ref}`search`