Lib/std/c/README.md

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