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
 102
 103 All `*.md` files can be converted to HTML by replacing the `.md`
 104 extension with `.html`. For example, use `make README.html` to generate
 105 an HTML file from the `.md` file. If the `.md` file is stored in Git, an
 106 extra footer with the text "Generated from *filename* revision *git-id*
 107 (*date*)" is added.
 108
 109 Uses `cmark`, available from <https://commonmark.org/>.
 110
 111 ### Create PDF
 112
 113 PDF files can be created from `.md` files by replacing `.md` with
 114 `.pdf`. To create `README.pdf`, execute `make README.pdf`. This will
 115 create an HTML file from the `.md` file which is then converted to PDF
 116 with [`wkhtmltopdf`](https://wkhtmltopdf.org/).
 117
 118 ## Download
 119
 120 The main Git repository is stored at GitLab:
 121
 122   - URL: <https://gitlab.com/oyvholm/STDexecDTS>
 123   - SSH clone: git@gitlab.com:oyvholm/STDexecDTS.git
 124   - https clone: <https://gitlab.com/oyvholm/STDexecDTS.git>
 125
 126 ## License
 127
 128 This program is free software; you can redistribute it and/or modify it
 129 under the terms of the GNU General Public License as published by the
 130 Free Software Foundation; either version 2 of the License, or (at your
 131 option) any later version.
 132
 133 This program is distributed in the hope that it will be useful, but
 134 WITHOUT ANY WARRANTY; without even the implied warranty of
 135 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
 136 Public License for more details.
 137
 138 You should have received a copy of the GNU General Public License along
 139 with this program. If not, see <http://www.gnu.org/licenses/>.
 140
 141 ## Author
 142
 143 Øyvind A. Holm \<<sunny@sunbase.org>\>
 144
 145 -----
 146
 147 File ID: STDuuidDTS
 148
 149 <!--
 150 vim: set ts=2 sw=2 sts=2 tw=72 et fo=tcqw fenc=utf8 :
 151 vim: set com=b\:#,fb\:-,fb\:*,n\:> ft=markdown :
 152 -->