Lib/std/c/README.md

   1 # README for STDexecDTS.git
   2
   3 ## About this document
   4
   5 This file is written in [Commonmark](https://commonmark.org) and all
   6 `make` commands use `cmark`(1) to generate HTML and reformat text.
   7
   8 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   9 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
  10 document are to be interpreted as described in RFC 2119.
  11
  12 ## Status
  13
  14 In the startup/design phase, does nothing yet.
  15
  16 ## Development
  17
  18 The `master` branch is considered stable, no unstable development
  19 happens there. Every new functionality or bug fix is created on topic
  20 branches which may be rebased now and then. All tests on `master`
  21 (executed with "make test") MUST succeed. If any test fails, it's
  22 considered a bug. Please report any failing tests in the issue tracker.
  23
  24 To ensure compatibility between versions, the program follows the
  25 Semantic Versioning Specification described at <http://semver.org>.
  26 Using the version number `X.Y.Z` as an example:
  27
  28   - `X` is the *major version*.
  29     This number is only incremented when backwards-incompatible changes
  30     are introduced.
  31   - `Y` is the *minor version*.
  32     Increased when new backwards-compatible features are added.
  33   - `Z` is the *patch level*.
  34     Increased when new backwards-compatible bugfixes are added.
  35
  36 ## `make` commands
  37
  38 ### make / make all
  39
  40 Generate the `STDexecDTS` executable.
  41
  42 ### make clean
  43
  44 Remove all generated files except `tags`.
  45
  46 ### make edit
  47
  48 Open all files in the subtree in your favourite editor defined in
  49 `EDITOR`.
  50
  51 ### make gcov
  52
  53 Generate test coverage with `gcov`(1). Should be as close to 100% as
  54 possible.
  55
  56 ### make gcov-cmt / make gcov-cmt-clean
  57
  58 Add or remove `gcov` markers in the source code in lines that are not
  59 tested. Lines that are hard to test, for example full disk, full memory,
  60 long paths and so on, can be marked with the string `/* gncov */` to
  61 avoid marking them. To mark lines even when marked with gncov, set the
  62 GNCOV environment variable to a non-empty value. For example:
  63
  64     make gcov-cmt GNCOV=1
  65
  66 These commands need the `gcov-cmt` script, available from
  67 <https://gitlab.com/oyvholm/utils/raw/master/gcov-cmt>.
  68
  69 ### make gdb
  70
  71 Start gdb with main() as the default breakpoint, this is defined in
  72 `src/gdbrc`. Any additional gdb options can be added in `src/gdbopts`.
  73 An example would be "-tty /dev/\[...\]" to send the program output to
  74 another window.
  75
  76 ### make install
  77
  78 `make install` installs `STDexecDTS` to the location defined by `PREFIX`
  79 in `src/Makefile`. Default location is `/usr/local`, but it can be
  80 installed somewhere else by specifying `PREFIX`. For example:
  81
  82     make install PREFIX=~/local
  83
  84 ### make tags
  85
  86 Generate `tags` file, used by Vim and other editors.
  87
  88 ### make test
  89
  90 Run all tests. This command MUST NOT fail on purpose on `master`.
  91
  92 ### make uninstall
  93
  94 Delete the installed version from `PREFIX`.
  95
  96 ### make valgrind
  97
  98 Run all tests with Valgrind to find memory leaks and other problems.
  99 Should also not fail on master.
 100
 101 ### Create HTML or PDF
 102
 103 `make html` creates HTML versions of all documentation in the current
 104 directory tree, and `make pdf` creates PDF versions.
 105
 106 All `*.md` files can be converted to HTML or PDF by replacing the `.md`
 107 extension with `.html` or `.pdf`. For example, use `make README.html` to
 108 generate an HTML file from the `.md` file, or `make README.pdf` to
 109 create a PDF version. If the `.md` file is stored in Git, an extra
 110 footer with the text "Generated from *filename* revision *git-id*
 111 (*date*)" is added.
 112
 113 Uses `cmark`, available from <https://commonmark.org/>.
 114
 115 ## Download
 116
 117 The main Git repository is stored at GitLab:
 118
 119   - URL: <https://gitlab.com/oyvholm/STDexecDTS>
 120   - SSH clone: git@gitlab.com:oyvholm/STDexecDTS.git
 121   - https clone: <https://gitlab.com/oyvholm/STDexecDTS.git>
 122
 123 ## License
 124
 125 This program is free software; you can redistribute it and/or modify it
 126 under the terms of the GNU General Public License as published by the
 127 Free Software Foundation; either version 2 of the License, or (at your
 128 option) any later version.
 129
 130 This program is distributed in the hope that it will be useful, but
 131 WITHOUT ANY WARRANTY; without even the implied warranty of
 132 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
 133 Public License for more details.
 134
 135 You should have received a copy of the GNU General Public License along
 136 with this program. If not, see <http://www.gnu.org/licenses/>.
 137
 138 ## Author
 139
 140 Øyvind A. Holm \<<sunny@sunbase.org>\>
 141
 142 -----
 143
 144 File ID: STDuuidDTS
 145
 146 <!--
 147 vim: set ts=2 sw=2 sts=2 tw=72 et fo=tcqw fenc=utf8 :
 148 vim: set com=b\:#,fb\:-,fb\:*,n\:> ft=markdown :
 149 -->