Skip to content

Latest commit

 

History

History
120 lines (104 loc) · 11.6 KB

README.md

File metadata and controls

120 lines (104 loc) · 11.6 KB
Raw

Dual licenses: choose Creative Commons or Apache 2 (allows all uses).

Table of Contents

Purposes

./posts/ stages posts (school classes) for https://SwuduSusuwu.SubStack.com/ about artificial neural tissue, antivirus, assistants, plus autonomous tools.

./c/ C implementations of posts (TODO, issue #3 which you can contribute to, or can request that more resources go to this task), + vendored code (for now just RFC6234, for sha2).

./cxx/ C++ implementations of posts (for now is just neural system pure virtual template (./cxx/ClassCns.hxx) + antivirus(./cxx/VirusAnalysis.cxx) + assistant(./cxx/AssistantCns.cxx), with lots of issues which you can contribute to, or can request that more resources go to).

How to use this

Minimum requirements (build targets which this supports):

Usage: ./build.sh [OPTIONS] produces objects (./obj/*.o, for distribution into other tools,) plus Executable and Linkable Format (./bin/a.out, to do examples/unit tests which prove how effective functions execute,) both of which you can redirect with export OBJDIR=___ (or export BINDIR=___.)

  • ./cxx/main.hxx has constants to use to interpret a.out's return values.
  • Console flags:
    • ./build.sh : Defaults to ./build.sh --debug. For all source code, if intermediate object doesn't exist or is older than source, builds source.
    • ./build.sh --clean : removes intermediate object files + exits; to reduce disc use.
    • ./build.sh --rebuild : removes intermediate object files + continues; to rebuild with new flags (or if ./build.sh doesn't rebuild code which includes updated headers).
    • ./build.sh --debug : includes frame-pointers/debug symbols (-g), includes valgrind-replacement tools (such as -fsanitize=address), optimizes with -Og.
    • ./build.sh --release : excludes --debug (-DNDEBUG), strips frame-pointers/symbols, optimizes with -O2.
    • ./build.sh --mingw : can mix with --release or --debug. Produces Portable Executable (./bin/a.exe), for Windows.
  • Special flags (vim build.sh to use); other than _PREFER_/_SKIP_, most use more resources if set to true:
    • Custom sh (console) output:
      • -DSUSUWU_SH_PREFER_STDIO to replace std::cXXX << ... with fprintf(stdXXX, ...); default is !defined(__cplusplus).
      • -DSUSUWU_SH_VERBOSE to print diagnostic messages (SUSUWU_SH_USE_FILE, SUSUEU_SH_USE_LINE, SUSUWU_NOTICE, SUSUWU_DEBUG, SUSUWU_DEBUGEXECUTE, SUSUWU_NOTICE_EXECUTE, SUSUWU_DEBUG_EXECUTE all use #if SUSUWU_SH_VERBOSE); default is !defined(NDEBUG).
      • -DSUSUWU_SH_SKIP_BRACKETS = true sets output format to WARN_LEVEL: message; default is false.
      • -DSUSUWU_SH_FILE = true sets output format to [__FILE__: WARN_LEVEL: message]; default is SUSUWU_SH_VERBOSE.
      • -DSUSUWU_SH_LINE = true sets output format to [__LINE__: WARN_LEVEL: message]; default is SUSUWU_SH_VERBOSE.
      • -DSUSUWU_SH_FUNC = true sets output format to [__func__: WARN_LEVEL: message]; default is false.
      • -DSUSUWU_SH_SKIP_COLORS = true to omit VT100 (ANSI) colors; default is defined(SUSUWU_SH_COLORS_UNSUPPORTED)).
      • -DSUSUWU_SH_SKIP_COLORS = false to force (even if unsupported) VT100 (ANSI) color use.
      • Flags which #17 will introduce (TODO):
        • -DSUSUWU_SH_RUNTIME_OSC to replace #ifdef _POSIX_VERSION\nAccessClipboard();\n#endif with termcmp/GetConsoleMode() (for choices on whether or not to use Operating System Commands); default is undefined.
        • -DSUSUWU_SH_RUNTIME_COLORS to replace #if _POSIX_VERSION\nColors();\n#endif with termcmp/GetConsoleMode() (for choices on whether or not to use colors); default is undefined.
    • To match g++/clang++ console format, use -DSUSUWU_SKIP_BRACKETS = true, -DSUSUWU_SH_FILE = true, -DSUSUWU_SH_LINE = true, -DSUSUWU_SH_FUNC = false, -DSUSUWU_SKIP_COLORS = false (sets output format to __FILE__:__LINE__: WARN_LEVEL: message).
    • TODO:

Contributor conventions/rules

Linter: clang-tidy cxx/*.cxx /* uses .clang-tidy options */

Git

Do atomic commits: if you cannot ./build.sh your commit if it is swapped (such as through git rebase -i) with a previous commit, or cannot ./build.sh if a previous commit got git revert, your commit message must include such as "Is followup to <commit hash>" (which shows temporal order).

git commit message format/syntax:

  • if commit does git add NewFile: message has +\NewFile``.
  • if git rm Exists: -Exists``.
  • if touch Exists && git add Exists: @\Exists`or?`Exists``.
    • Simple wildcards/regex for altered functions: \%s/oldFunction/newFunction/``.
  • if echo "int newFunction() {...}" >> Exists && git add Exists: @\Exists`:+`NewFunction()``.
  • if git mv OldPath/ NewPath/: \OldPath/.* -> NewPath/.*``.

[Notice: Commit titles can omit backticks (``) if not enough room; the backticks just allow GitHub to format code/paths.]

Source

Most of what Mozilla Org's (Firefox's) style suggests is sound (you should follow this unless you have specific reasons not to). Code rules (lots overlap with Mozilla Org's):

  • Files: #include "PascalCase.hxx", as this is most common. ./build.sh requires: that all local includes prefix as Class*.hxx (so it knows to execute --rebuild if you upgrade a common include.) TODO: incremental builds which don't require this.

  • Structs, enums, classe: typedef struct PascalCase {} PascalCase;, typedef enum PascalCase {} PascalCase;, typedef class PascalCase {} PascalCase;, as this is most common.

  • Macros: #define NAMESPACE_CONSTANT_CASE(snake_case_param) assert(snake_case_param);, as this is most common.

  • Indent: tabs ('^I', reduced memory use, allows local configs to set width, allows arrow keys to move fast); as much tabs as braces ('{', '}'). [All which conflicts with Mozilla Org's format is tab use.]

  • Braces, functions; most common form:

const /* const prevents `if(func() = x)` where you wished for `if(func() == x)` */ bool classPrefixCamelCase(bool s, bool x) {
    if(s && x) {
        return s;
    } else {
        return x;
    }
}

  • Local variables, objects: const bool camelCase = true; Global variables/objects: extern const bool classPrefixCamelCase;, as this is most common.

    • Functions/globals can omit "classPrefix" if the file has namespace used to avoid collisions, or has class used to mask member typedefs/functions.
    • [The project as a whole should have namespace, but you can nest namespaces.]

  • Include guards:

#ifndef INCLUDES_Path_To_File
#define INCLUDES_Path_To_File
#endif /* ndef INCLUDES_Path_To_File */

/* @throw std::bad_alloc If function uses {malloc, realloc, new[], std::*::{push_back, push_front, insert}}
 * @throw std::logic_error Optional. Would include most functions which use std::*
 * @pre @code !output.full() @endcode
 * @post @code !output.empty() @endcode
 */
bool functionDeclaration(std::string input, std::deque<vector> output);
  • It is arguable whether or not you should document such possible system errors; almost all Standard Template Library functions can throw derivatives of std::logic_error.
  • Regex :%s/@pre (.*) @code (.*) @endcode/[[expects: \2]] \\* \1 \\*/ :%s/@post (.*) @code (.*) @endcode/[[ensures: \2]] \\* \1 \\*/ once have Contracts/C++26.
  • cxx/Macros.cxx has ASSUME(X), which is close to [[expects: x]], but ASSUME(X) goes to *.cxx, whereas [[expects]] goes to *.hxx.
  • Documentation of interfaces belongs to *.hxx; *.cxx is to do implementations. Do not duplicate interface comments.
  • Advantages of [[expects]]; allows to move information of interfaces out of *.cxx, to *.hxx.