diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/dergods_style_v0.1.ms | 24 | ||||
| -rw-r--r-- | docs/dergods_style_v0.1.org | 104 | ||||
| -rw-r--r-- | docs/dergods_style_v0.1.pdf | bin | 0 -> 16976 bytes | |||
| -rw-r--r-- | docs/index.php | 1 | ||||
| -rw-r--r-- | docs/lowbat.org | 62 |
5 files changed, 191 insertions, 0 deletions
diff --git a/docs/dergods_style_v0.1.ms b/docs/dergods_style_v0.1.ms new file mode 100644 index 0000000..7ff38d0 --- /dev/null +++ b/docs/dergods_style_v0.1.ms @@ -0,0 +1,24 @@ +.TL +Dergods' Style and good practices for C/C++ projects +.AU +Joe +.PP +My cool roff document . +aze&é"" +.PP +This is a new paragraph +It this going to be annoying? +I have to save twice. + +Is it ok now? +Maybe now? +Ok cool af + +Working +qweqwe + +Now we can write some text +.PP +Pretty +.B cool +huh diff --git a/docs/dergods_style_v0.1.org b/docs/dergods_style_v0.1.org new file mode 100644 index 0000000..7d27312 --- /dev/null +++ b/docs/dergods_style_v0.1.org @@ -0,0 +1,104 @@ +#+TITLE: Dergods' Style and good practices for C/C++ +#+AUTHOR: Joe +#+DATE: v0.1 +#+LATEX_CLASS: article +#+LATEX_CLASS_OPTIONS: [a4paper] +#+LATEX_HEADER: \usepackage[margin=1.0in]{geometry} +#+LATEX_HEADER: \usepackage[utf8]{inputenc} +#+LATEX_HEADER: \usepackage[dvipsnames]{xcolor} +#+LATEX_HEADER: \definecolor{mypink1}{rgb}{0.858, 0.188, 0.478} +#+LATEX_HEADER: \let\OldTexttt\texttt +#+LATEX_HEADER: \renewcommand{\texttt}[1]{% +#+LATEX_HEADER: \OldTexttt{% +#+LATEX_HEADER: \colorbox{gray}{% +#+LATEX_HEADER: \color{black} #1% +#+LATEX_HEADER: }% +#+LATEX_HEADER: }% +#+LATEX_HEADER: }% + +* Introduction +The following is a description of Dergods' Style code and project +formatting to put in use if you work on Dergods' Realm-related code or if you +just need a personnal good-looking norm to improve your code readablity. It +is heavily inspired by BSD [[https://www.freebsd.org/cgi/man.cgi?query=style&apropos=0&sektion=0&manpath=FreeBSD+12.1-RELEASE+and+Ports&arch=default&format=html][style(9)]], +with some changes. + +* Projects and version control +** Directories + - Working on a *program*: + - All source and header files should be in the ~src/~ directory. + - Necessary media files such as images, sounds, fonts, etc... To the program execution should be in the ~media/~ directory. + - Compilation-generated object files should be located in the ~obj/~ directory. + - Sub-programs or utilities should be located in the ~tools/~ directory. + - An optional man page can be made for the program and should be located in the ~man/~ directory. + - Working on a *library*: + - All source files should be located in the ~src/~ directory. + - Compilation-generated object files should be located in the ~obj/~ directory. + - Non-optional man pages for every major function should be located in the ~man/~ directory. + - Header files should be located in the ~include/~ directory. + +** Files + - *C* sources and headers files should be of the ~.c~ and ~.h~ extensions. + - *C++* sources and header files should be of the corresponding ~.cxx~ / ~.hxx~ or ~.cc~ / ~.hh~ extensions unless the project is Microsoft™ Windows®-compatible only, then extensions should be ~.cpp~ / ~.hpp~. If the project is compatible with any UNIX®-like operating system, ~.cxx~ / ~.hxx~ or ~.cc~ / ~.hh~ should be the prefered extensions. + - Compilation-generated object files should be of the ~.c.o~, ~.cxx.o~, ~.cc.o~ or ~.cpp.o~ corresponding to the correct extensions. + - All files should follow the UNIX® case formatting, including only lowercase alphabetical letters (~a-z~), underscores (~_~) and dots (~.~). Numbers are not allowed. + - Compilation-generated object files should have the same pre-extension basename as its the corresponding source file. + - Working on a *program*, every source file should have its own header file. The pre-extension basenames names should be corresponding. Orphan header files are tolerated. + - Source files should be composed of two parts: + - An index letter followed by an underscore (~_~). An index letters list should be found in an info comment under the main function. The index letter should be consistent. + - A single explicit word describing the file's purpose. + - Example of what a source file should look like: ~g_inventory.cxx~. Its corresponding header file should be ~g_inventory.hxx~ and its compilation-generated object file should be ~g_inventory.cxx.o~. In our case, ~g_~ may be described under the main function as gameplay-related. + - ~.txt~ format is pointless and forbidden. + - Don't forget a LICENSE and a README. Prefer org-mode or markdown for README if the project is going to be published on platforms such as GitLab or GitHub. Therefore extensions should be ~.org~ or ~.md~. You can add a copy of the README without extension properly formatted to be displayed in a terminal or platforms that do not handle org-mode or markdown. + +** Makefile + - The project should always contain at least one makefile. + - There can be more more than one makefile per projects but only one by subdirectories. + - The makefile should be in lowercases only with a capital "M": ~Makefile~. + - The main makefile should contain at least the 3 rules: + - ~all~ + - ~clean~ + - ~install~ + - Makefiles should not relink upon successful compilation. + - The main makefile should contain rules to compile any sub makefiles with the ~tools~ rule. + - All compiled binaries and libraries should be in the root of the project repository, next to the main makefile. + +** Compilation + - The compiler of choice for released binaries should be ~clang~ for C and ~clang++~ for C++. + - The program should compile with ~gcc~ or ~g++~ as well, so test those often. + - C standard of choice should be ~C89~. + - C++ standard of choice should be ~C++98~. + - ~C99~ is tolerated sometimes but ~C89~ should always be this first choice. + - Standard compiler flags should be: + - ~-std=c89~ for C or ~-std=c99~ for C++. + - ~-Wall~ + - ~-Wextra~ + - ~-Werror~ + - ~-pedantic~ + - When including external libraries, additional ~-Wno-~\x X flags may be added to mute external warnings generated by them, for example if one library uses a more recent standard. + - Example: ~-Wno-long-long~ if your library uses ~long long~'s. You will then have to be careful not using ~long long~'s in your code. + - Released binaries should never be compiled with ~-g~\x X options. + - The program should run without any issue with the ~-fsanitize=address~ or ~-fsanitize=memory~ options engaged. Test those often. + - Dynamic linking is prefearable. + +** Editors +No specific editor should be imposed over another, you should always pick the +one you feel the more comfortable with. However some of them are malicious +spyware that should never be recommanded. + +Here is a non-exhaustive list of recommanded or banished programs: + + - *Recommanded*: + - vi® / vim® and variants + - GNU Emacs® + - ee® + - joe® and variants + - *banished*: + - Microsoft™ VSCode® + - Microsoft™ Atom® + - JetBrains™ IntelliJ® variants + +** Version control + - Prefer ~fossil~ over ~git~. Using ~fossil~'s builtin function to mirror repository to ~git~ is fine. + - The repository should only contain files necessary to the compilation, execution or documentation of the program. + - The repository root should not contain anything else than the project's main makefile, LICENSE, README and subdirectories. diff --git a/docs/dergods_style_v0.1.pdf b/docs/dergods_style_v0.1.pdf Binary files differnew file mode 100644 index 0000000..733c5a9 --- /dev/null +++ b/docs/dergods_style_v0.1.pdf diff --git a/docs/index.php b/docs/index.php new file mode 100644 index 0000000..d29ead0 --- /dev/null +++ b/docs/index.php @@ -0,0 +1 @@ +<?php header("Location: ../"); ?> diff --git a/docs/lowbat.org b/docs/lowbat.org new file mode 100644 index 0000000..a2fc8a5 --- /dev/null +++ b/docs/lowbat.org @@ -0,0 +1,62 @@ +#+TITLE: lowbat - lightweight low battery notifier + +* Why lowbat? + I've been using minimalist OS installations for work, personnal computing +and playing video games for a while now. I used [[https://www.archlinux.org/][Arch Linux]], I still use +[[https://gentoo.org/][Gentoo Linux]] - which is by far my favorite Linux distribution - as a desktop +OS, and now I am using [[https://www.freebsd.org/][FreeBSD]] on my workstation. + +Those operating systems and distributions basically come with a kernel, +coreutils, a shell and that's pretty much it. Everything else has to be +installed manually. I love this philosophy, the simplicity behind it and the +fact that you know exactly what's on your system at any moment. + +As window managers, I used [[http://dwm.suckless.org/][dwm]] for a while, and I am now using [[https://github.com/baskerville/bspwm][bspwm]]. They +are ultra-fast, very lightweight and do not bring extra bloatware to my systems. +I do not use a status bar as well, I like my applications to use the full screen +space available. + +A big problem for me with this setup for me was that they do not come with some +kind of warning or notification system, like fancier desktop environments would, +when my laptop battery is low. That also was before I started using *Emacs*, +discovering the battery level indicator in the modeline. Ultimatly the +frustration was too important when the computer kept shutting down in +the middle of important work too many time. Then I decided to create *lowbat* +to cure this issue. + +* History of lowbat + It started as a very short ~dash~ shell (get [[https://github.com/tklauser/dash][dash]] here) script that was +working fine but I wanted to experiment a little bit with this. It turned into +a ~C++~ program, which is still the case for the GNU/Linux version. +Switching to FreeBSD, I exerimented again by turning it into an +~x64 assembly~ program, following the *Intel* syntax. In that way *lowbat* is +even more lightweight and consumes less battery power. +These days, I am rewriting it in the *AT&T* syntax. + +* How it works +** libnotify lowbat + The principle of *lowbat* is rather simple. When it's running in the +background, it checks every 4 minutes whether your battery is above 15%. +If that is the case, it sleeps for another 4 minutes. When your battery runs +bellow 15%, *lowbat* checks your battery level every 20 seconds as well as +sending you a *notification* using ~libnotify~. You can display live +notifications on your desktop using ~dunst~ for example, as well as many +other I'm sure. + +#+CAPTION: A notification generated by lowbat, displayed by dunst +#+NAME: fig:lowbat-example +[[../img/lowbat-01.jpg]] + +** espeak lowbat + *lowbat* also has an option to send a custom voice message to the use +using ~espeak~. Very handy if you are not in front of your computer or +if you want to bring joy to this dramatic event. + +** unknown lowbat + Sadly, I wasn't able to test lowbat on machines with more that one +battery. My call is that it will only warn you for the /first/ battery, +but I can't be sure. Try it and tell me! + +* Links to lowbat + - GNU/Linux: [[https://github.com/JozanLeClerc/lowbat][lowbat's GitHub GNU/Linux repository]] + - BSD: [[https://github.com/JozanLeClerc/lowbat-bsd][lowbat's GitHub BSD repository]] |