carbon

The ultimate high-level library for C/C++ (с реализацией на этих языках). 🎩

https://github.com/sparky-game/carbon

Keywords

Repository

The ultimate high-level library for C/C++ (с реализацией на этих языках). 🎩

.github/README.org

#+AUTHOR: Wasym A. Alonso

# Cover
#+begin_html



#+end_html

# Badges
#+begin_html









#+end_html

#+begin_quote
~Carbon~ has been a dream so far, we haven't found a single bug and it's super easy to work with. (⸮)

- ¯\_(ツ)_/¯
#+end_quote

~Carbon~ (/[[https://en.wikipedia.org/wiki/Help:IPA/English][\slash{}ˈkɑːbᵊn\slash{}]]/) is the ultimate *tiny* and *easy to use* high-level library for C/C++ (/с реализацией на этих языках/). @@html:
@@
It even can be used to test any piece of C/C++ code; thus, working as a full-fledged *testing suite*. @@html:
@@
If you'd like to make a contribution, you can check the project's [[CONTRIBUTING.org][guidelines]]; also, keep an eye on both security issues reporting [[../SECURITY.md][instructions]] and our [[../CODE_OF_CONDUCT.md][Code of Conduct]]. Furthermore, if you do something cool with /Carbon/, don't forget to add the [[https://github.com/topics/sk-cbn][#sk-cbn]] tag to your /topics/! 👍

-----

We use *CI/CD* to ensure the final product has the expected level of quality, if not more 🚀. This is the summary of the pipelines being run:

| *Kind*                        | *Target*          | *Status*                                                                                                                                                                |
| CI (/Continuous Integration/) | /master/          | @@html:@@   |
| CD (/Continuous Delivery/)    | /master/          | @@html:@@   |
| CD (/Continuous Deployment/)  | /master/docs/www/ | @@html:@@ |

-----

Do you want to *keep up with changes* or do you have a *question* that doesn't require you to open an issue? @@html:
@@
Join the [[https://github.com/sparky-game/carbon/discussions][GitHub Discussions]] forum, meet other users like you. The more we are, the better for everyone. @@html:
@@
There you can ask questions, exchange ideas, share some of your work, make polls, stay up to date with new updates and announcements of the library, and much more.

Do you want to support ~Carbon~? Consider becoming a [[https://github.com/sponsors/iWas-Coder][sponsor]], or making a donation via [[https://ko-fi.com/iwas_coder][Ko-fi]] or [[https://buymeacoffee.com/iwas.coder][Buy Me a Coffee]].
Many thanks to *all of you* who are reading this; I hope it'll be useful and it'll make you *enjoy programming* a little bit more.

#+begin_quote
[!WARNING]
~Carbon~ is currently in an *alpha* quality stage, and is not production-ready yet.
#+end_quote

* Table of Contents :toc:
- [[#usage][Usage]]
  - [[#get-the-code][Get the code]]
  - [[#build-from-source][Build from source]]
  - [[#examples][Examples]]
- [[#licensing][Licensing]]
- [[#references][References]]

* Usage

/Carbon/ is in essence a two-part library: the *static/dynamic lib pkg* itself (where all symbols and instructions are defined), and the *C/C++ header file* (which gets generated by the build process as an amalgamation of all internal headers the library uses).

** Get the code

We can get /Carbon/ in our preferred way of managing dependencies or external libraries in our projects. It's important to do so via the *OFFICIAL* Git repository hosted on [[https://github.com/sparky-game/carbon][GitHub]], and not through any other website or server. Appart from that, any ref can be checked out, being ~master~ (the trunk of all dev progress), a tagged commit (e.g. ~v1.0~), an actively maintained version branch (e.g. ~v1.0.y/stable~) or a LTS version branch (e.g. ~v1.0.y/lts~) the preferred ones.

Here are the main options of obtaining it:

*Git Clone:*

#+begin_src sh
git clone --recursive https://github.com/sparky-game/carbon
#+end_src

*Git Submodule:*

#+begin_src sh
git submodule add https://github.com/sparky-game/carbon vendor/carbon
git submodule update --init --recursive
#+end_src

*CMake FetchContent:*

#+begin_html
  —  Мои соболезнования.
#+end_html

#+begin_src cmake
include(FetchContent)
FetchContent_Declare(
  carbon
  GIT_REPOSITORY "https://github.com/sparky-game/carbon"
  GIT_TAG        [...]
  GIT_PROGRESS   TRUE
)
FetchContent_MakeAvailable(carbon)
#+end_src

*Pre-compiled Package:*

You might want to take a look to the [[https://github.com/sparky-game/carbon/releases/latest][latest release available]] and download the appropriate pre-compiled package for your CPU's architecture and OS.

** Build from source

If wanted to build /Carbon/ from source yourself, it can be done without any problems. We use a custom ~make~ utility (which uses /Carbon/ under the hood) as our build system to manage testing, compiling and packaging the library, both static and dynamic.

This custom build system can rebuild itself properly (using our preferred compilation flags), which means that you'll only need to bootstrap it once:

#+begin_src sh
cc src/make.c -o make
#+end_src

Once built, we can take a look at the available subcommands and options by issuing the command ~./make help~. To run the full build pipeline it's just as easy as:

#+begin_src sh
./make
#+end_src

#+begin_quote
[!TIP]
Checkout the [[../INSTALL][installation instructions]] to make /Carbon/ available on your system as any other library (the ~PREFIX~ is customizable according to your needs).
#+end_quote

** Examples

A good place to start learning and discovering all the things you can do with /Carbon/ is *reading* and *executing* the [[../examples][examples]]. One can issue the command ~./make examples~ to build them all: for each example source file (~.c~ or ~.cc~) it produces a ~.bin~ executable file, which can be run normally without problems.

Furthermore, you can also take a look at the amalgamated distributable *header file* (~carbon.h~), where each module of the library is declared and documented. This is all the documentation you'll ever need, and it's also a good place to find new things /Carbon/ can do.

Lastly, for a more advanced understanding of all available and tested functionality that /Carbon/ provides, *reading* the [[../test][tests]] is a great next step. There it can be learnt both how to work with the different modules, and how to use /Carbon/ itself to test your own applications and programs. One can issue the command ~./make test~ to build and run all tests.

* Licensing

Copyright (C) Wasym A. Alonso. All Rights Reserved.

#+begin_quote
/Carbon/ is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License Version 3 (GNU AGPL-3.0) as published by the Free Software Foundation (FSF) on November 19th 2007. @@html:
@@
/Carbon/ is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License Version 3 for more details. @@html:
@@
For more information, see .
#+end_quote

As mentioned above, /Carbon/ is licensed under the GNU's *AGPL-3.0-only*, which means that any software created or that uses it is also subject to the same license. This implies that if you develop an application using /Carbon/, it must also be released as free software under the GNU's *AGPL-3.0-only*. This ensures that the freedoms to use, study, modify and share the software are preserved for everyone.

If you prefer to release your application under a different, more commercially friendly license, there is an option available. You can purchase a copy of the *Carbon Runtime Library Exception (CRLE)*, which is in essence a /distinct commercial license/, for you to use this library without releasing your software under GNU's *AGPL-3.0-only*. Some key aspects of the *CRLE* are the following:
- *One-Time Purchase (OTP):* Once obtaining a copy of the CRLE, it lasts forever without expiration date.
- *Project-specific:* Each CRLE is tied to a single project of yours.
- *Version compatibility:* Each CRLE applies to a specific branch or minor version of /Carbon/ (e.g. ~v1.0.y/lts~), enabling you to update the library to a more up-to-date version with the same CRLE.
- *Professional support:* You also gain access to more advanced support regarding the library, as well as a private channel to make high-priority requests such as bug fixes or security vulnerabilities.

For more details and to acquire a copy of the *CRLE*, please visit .

* References

1. Alshahwan, N., Chheda, J., Finegenova, A., Gokkaya, B., Harman, M., Harper, I., Marginean, A., Sengupta, S., Wang, E. (2024, February 14). /Automated Unit Test Improvement using Large Language Models at Meta/ [Paper]. arXiv, Cornell University. 
2. Barrett, S. (2015, June 7). /Advice for Writing Small Programs in C/ [Video]. YouTube. 
3. Catto, E. (2024, August 27). /Determinism/ [Article]. Box2D. 
4. Christensen, T. (2002, January 1). /The Cambridge History of Western Music Theory/ [Book]. Cambridge University Press. 
5. Gallego Durán, F. J. (2021, December 7). /C++ Slotmap: qué es y por qué usarlo en tu motor de videojuegos/ [Video]. YouTube. 
6. Gallego Durán, F. J. (2021, December 10). /C++ Programamos un Slotmap para nuestro motor de videojuegos ECS/ [Video]. YouTube. 
7. Gallego Durán, F. J. (2022, January 28). /C++ Template Metaprogramming: Introducción/ [Video]. YouTube. 
8. Gallego Durán, F. J. (2022, March 2). /C++ Operadores: cómo programar un vector 3D/ [Video]. YouTube. 
9. Holden, D. (2021, April 16). /orangeduck/Cello: Higher level programming in C/ [Code]. GitHub. 
10. Immisch, L., Wilstrup C. (2017, January 1). /PCM Terminology and Concepts/ [Article]. pyalsaaudio's Website. 
11. Kutepov, A. (2023, June 30). /tsoding/nn.h: Simple stb-style header-only library for Neural Networks/ [Code]. GitHub. 
12. Kutepov, A. (2024, November 5). /tsoding/nob.h: Next generation of the NoBuild idea/ [Code]. GitHub. 
13. Kutepov, A. (2025, February 3). /tsoding/coroutines: Custom coroutines implementation in GNU C/ [Code]. GitHub. 
14. Matsumoto, M., Nishimura, T. (1998, January 1). /Mersenne twister: a 623-dimensionally equidistributed uniform pseudo-random number generator/ [Paper]. Transactions on Modeling and Computer Simulation (TOMACS), Association for Computing Machinery (ACM). 
15. Matsumoto, M., Nishimura, T. (2004, September 29). /A C-program for MT19937-64 (2004/9/29 version)/ [Code]. Department of Mathematics, Hiroshima University. 
16. Nishimura, T. (2000, October 1). /Tables of 64-bit Mersenne twisters/ [Paper]. Transactions on Modeling and Computer Simulation (TOMACS), Association for Computing Machinery (ACM). 
17. OptumSoft. (2016, January 5). /Dangers of using dlsym() with RTLD_NEXT/ [Article]. OptumSoft. 
18. Rice, B. (2018, January 23). /You Can't Unit Test C, Right?/ [Video]. YouTube. 
19. Viotti, J. C. (2023, December 1). /Understanding Objective-C by transpiling it to C++/ [Article]. jviotti.com. 

Owner

Citation (CITATION.cff)

cff-version: 1.2.0
message: "Please cite this software using these metadata."
type: software
title: Carbon
authors:
  - given-names: Wasym
    family-names: Atieh Alonso
contact:
  - given-names: Wasym
    family-names: Atieh Alonso
    email: wasymatieh01@gmail.com
abstract: "The ultimate high-level library for C/C++ (с реализацией на этих языках)."
license: AGPL-3.0-only
repository-code: "https://github.com/sparky-game/carbon"

GitHub Events

Issues and Pull Requests

Last synced: 6 months ago