doc/man/barectf.1

   1 '\" t
   2 .\"     Title: barectf
   3 .\"    Author: [see the "AUTHORS" section]
   4 .\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
   5 .\"      Date: 11/15/2016
   6 .\"    Manual: barectf manual
   7 .\"    Source: barectf 2.2.1
   8 .\"  Language: English
   9 .\"
  10 .TH "BARECTF" "1" "11/15/2016" "barectf 2\&.2\&.1" "barectf manual"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 barectf \- Generate C99 code that can write native CTF packets
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 \fBbarectf\fR [\fB--prefix\fR=\fIPREFIX\fR] [\fB--dump-config\fR]
  36         [\fB--code-dir\fR=\fIPATH\fR] [\fB--headers-dir\fR=\fIPATH\fR] [\fB--metadata-dir\fR=\fIPATH\fR]
  37         [\fB-I\fR \fIPATH\fR]\&... [\fB--ignore-include-not-found\fR] \fICONFIG\fR
  38 .fi
  39 .SH "DESCRIPTION"
  40 .sp
  41 The \fBbarectf\fR command generates C99 code, that itself can write Common Trace Format <http://diamon.org/ctf> packets natively, out of a YAML configuration input file \fICONFIG\fR\&. The full documentation of barectf is available on the project\(cqs website <http://barectf.org>\&.
  42 .sp
  43 A prefix is used to scope the generated file names, as well as the generated function names, macro names, structure names, and so on\&. By default, this prefix is \fBbarectf_\fR\&. It can be overridden by the configuration file, and ultimately by the \fB--prefix\fR option\&.
  44 .sp
  45 By default, all generated C and CTF metadata files are written to the current working directory\&. The \fB--code-dir\fR, \fB--headers-dir\fR, and \fB--metadata-dir\fR options are used to control where the generated files should go\&.
  46 .sp
  47 You can add directories to be searched into for inclusion files, before the default search directories, by using the \fB-I\fR option one or more times\&.
  48 .sp
  49 By default, if an inclusion file is not found while processing the configuration file \fICONFIG\fR, an error is emitted\&. You can instruct \fBbarectf\fR to continue silently instead by providing the \fB--ignore-include-not-found\fR option\&.
  50 .sp
  51 To view the effective YAML configuration file used for generating the C and CTF metadata files, after having processed all inclusion files, use the \fB--dump-config\fR option\&.
  52 .SH "OPTIONS"
  53 .PP
  54 \fB-c\fR \fIPATH\fR, \fB--code-dir\fR=\fIPATH\fR
  55 .RS 4
  56 Write C source files to directory
  57 \fIPATH\fR
  58 instead of the current working directory\&.
  59 .RE
  60 .PP
  61 \fB--dump-config\fR
  62 .RS 4
  63 Dump the effective YAML configuration file, after all inclusions are processed, to the standard output\&.
  64 .RE
  65 .PP
  66 \fB-H\fR \fIPATH\fR, \fB--headers-dir\fR=\fIPATH\fR
  67 .RS 4
  68 Write C header files to directory
  69 \fIPATH\fR
  70 instead of the current working directory\&.
  71 .RE
  72 .PP
  73 \fB--ignore-include-not-found\fR
  74 .RS 4
  75 Do not consider as an error inclusion files that are not found: continue silently\&.
  76 .RE
  77 .PP
  78 \fB-I\fR \fIPATH\fR, \fB--include-dir\fR=\fIPATH\fR
  79 .RS 4
  80 Prepend
  81 \fIPATH\fR
  82 to the list of directories to search into for include files\&. The default list of directories is the current working directory, followed by the directory containing the provided, "standard" inclusion files\&.
  83 .RE
  84 .PP
  85 \fB-m\fR \fIPATH\fR, \fB--metadata-dir\fR=\fIPATH\fR
  86 .RS 4
  87 Write CTF metadata file to directory
  88 \fIPATH\fR
  89 instead of the current working directory\&.
  90 .RE
  91 .PP
  92 \fB-p\fR \fIPREFIX\fR, \fB--prefix\fR=\fIPREFIX\fR
  93 .RS 4
  94 Override the configuration file\(cqs prefix with
  95 \fIPREFIX\fR\&. This prefix is used in file names, function names, macro names, structure names, and the rest\&. When not specified in the configuration file, the default prefix is
  96 \fBbarectf_\fR\&.
  97 .RE
  98 .PP
  99 \fB-h\fR, \fB--help\fR
 100 .RS 4
 101 Show command help\&.
 102 .RE
 103 .PP
 104 \fB--version\fR
 105 .RS 4
 106 Show the command\(cqs version\&.
 107 .RE
 108 .SH "EXIT STATUS"
 109 .PP
 110 \fB0\fR
 111 .RS 4
 112 Success
 113 .RE
 114 .PP
 115 \fBNot 0\fR
 116 .RS 4
 117 Error
 118 .RE
 119 .SH "BUGS"
 120 .sp
 121 Please report any bug or usability issue as a GitHub issue <https://github.com/efficios/barectf/issues>\&.
 122 .SH "RESOURCES"
 123 .sp
 124 .RS 4
 125 .ie n \{\
 126 \h'-04'\(bu\h'+03'\c
 127 .\}
 128 .el \{\
 129 .sp -1
 130 .IP \(bu 2.3
 131 .\}
 132 Project\(cqs website <http://barectf.org>
 133 .RE
 134 .sp
 135 .RS 4
 136 .ie n \{\
 137 \h'-04'\(bu\h'+03'\c
 138 .\}
 139 .el \{\
 140 .sp -1
 141 .IP \(bu 2.3
 142 .\}
 143 Continuous integration <http://ci.lttng.org/job/barectf>
 144 .RE
 145 .sp
 146 .RS 4
 147 .ie n \{\
 148 \h'-04'\(bu\h'+03'\c
 149 .\}
 150 .el \{\
 151 .sp -1
 152 .IP \(bu 2.3
 153 .\}
 154 Mailing list <http://lists.lttng.org>
 155 for support and development:
 156 \fBlttng-dev@lists.lttng.org\fR
 157 (prefix the subject message with
 158 \fB[barectf]\fR)
 159 .RE
 160 .sp
 161 .RS 4
 162 .ie n \{\
 163 \h'-04'\(bu\h'+03'\c
 164 .\}
 165 .el \{\
 166 .sp -1
 167 .IP \(bu 2.3
 168 .\}
 169 IRC channel <irc://irc.oftc.net/lttng>:
 170 \fB#lttng\fR
 171 on
 172 \fBirc.oftc.net\fR
 173 (\fBeepp\fR
 174 is barectf\(cqs author and maintainer)
 175 .RE
 176 .SH "COPYRIGHT"
 177 .sp
 178 Copyright (c) 2014\-2016 Philippe Proulx <mailto:pproulx@efficios.com>\&.
 179 .sp
 180 barectf is distributed under the MIT License <https://github.com/efficios/barectf/blob/master/LICENSE>\&.
 181 .SH "AUTHORS"
 182 .sp
 183 barectf was originally written by and is maintained by, as of this version, Philippe Proulx <mailto:pproulx@efficios.com>\&. Other, nice people have since contributed to the project\&.
 184 .sp
 185 barectf is supported by EfficiOS <http://www.efficios.com/>\&.