modernc.org/ccgo/v3@v3.16.14/doc.go (about) 1 // Copyright 2020 The CCGO Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style 3 // license that can be found in the LICENSE file. 4 5 // Command ccgo is a C compiler producing Go code. 6 // 7 // Usage 8 // 9 // Invocation 10 // 11 // ccgo { option | input-file } 12 // 13 // Changelog 14 // 15 // 2021-12-23: v3.13.0 add clang support. 16 // 17 // Libc 18 // 19 // To compile the resulting Go programs the package modernc.org/libc has to be 20 // installed. 21 // 22 // Environment variables 23 // 24 // CCGO_CPP selects which command is used by the C front end to obtain target 25 // configuration. Defaults to `cpp`. Ignored when --load-config <path> is used. 26 // 27 // TARGET_GOARCH selects the GOARCH of the resulting Go code. Defaults to 28 // $GOARCH or runtime.GOARCH if $GOARCH is not set. Ignored when --load-config 29 // <path> is used. 30 // 31 // TARGET_GOOS selects the GOOS of the resulting Go code. Defaults to $GOOS or 32 // runtime.GOOS if $GOOS is not set. Ignored when --load-config <path> is used. 33 // 34 // Compiling 35 // 36 // To compile for the host invoke something like 37 // 38 // ccgo -o foo.go bar.c baz.c 39 // 40 // Cross compiling 41 // 42 // To cross compile set TARGET_GOARCH and/or TARGET_GOOS, not GOARCH/GOOS. 43 // Cross compile depends on availability of C stdlib headers for the target 44 // platform as well on the set of predefined macros for the target platform. 45 // For example, to cross compile on a Linux host, targeting windows/amd64, it's 46 // necessary to have mingw64 installed in $PATH. Then invoke something like 47 // 48 // CCGO_CPP=x86_64-w64-mingw32-cpp TARGET_GOOS=windows TARGET_GOARCH=amd64 49 // ccgo -o foo.go bar.c baz.c 50 // 51 // Input files 52 // 53 // Only files with extension .c, .h or .json are recognized as input files. 54 // 55 // A .json file is interpreted as a compile database. All other command line 56 // arguments following the .json file are interpreted as items that should be 57 // found in the database and included in the output file. Each item should be 58 // on object file (.o) or static archive (.a) or a command (no extension). 59 // 60 // Options with arguments 61 // 62 // Command line options requiring an argument. 63 // 64 // Define a preprocessor macro 65 // 66 // -Dfoo 67 // 68 // Equals `#define foo 1`. 69 // 70 // -Dfoo=bar 71 // 72 // Equals `#define foo bar`. 73 // 74 // Setting include search path 75 // 76 // -Ipath 77 // 78 // Add path to the list of include files search path. The option is a capital 79 // letter I (India), not a lowercase letter l (Lima). 80 // 81 // Linking with other ccgo-generated packages 82 // 83 // -limport-path 84 // 85 // The package at <import-path> must have been produced without using the 86 // -nocapi option, ie. the package must have a proper capi_$GOOS_$GOARCH.go 87 // file. The option is a lowercase letter l (Lima), not a capital letter I 88 // (India). 89 // 90 // Undefine a preprocessor macro 91 // 92 // -Ufoo 93 // 94 // Equals `#undef foo`. 95 // 96 // Generating JSON compilation database 97 // 98 // -compiledb name 99 // 100 // When this option appears anywhere, most preceding options are ignored and 101 // all following command line arguments are interpreted as a command with 102 // arguments that will be executed to produce the compilation database. For 103 // example: 104 // 105 // ccgo -compiledb compile_commands.json make -DFOO -w 106 // 107 // This will execute `make -DFOO -w` and attempts to extract the compile and 108 // archive commands. 109 // 110 // Only POSIX operating systems are supported. 111 // 112 // The supported build system must output information about entering 113 // directories that is compatible with GNU make. 114 // 115 // The only compilers supported are `gcc` and `clang`. 116 // 117 // The only archiver supported is `ar`. 118 // 119 // Format specification: https://clang.llvm.org/docs/JSONCompilationDatabase.html 120 // 121 // Note: This option produces also information about libraries created with `ar 122 // cr` and include it in the json file, which is above the specification. 123 // 124 // Setting C runtime library import path 125 // 126 // -crt-import-path path 127 // 128 // Unless disabled by the -nostdlib option, every produced Go file imports the 129 // C runtime library. Default is `modernc.org/libc`. 130 // 131 // Exporting C defines 132 // 133 // -export-defines "" 134 // 135 // Export C numeric/string defines as Go constants by capitalizing the first 136 // letter of the define's name. 137 // 138 // -export-defines prefix 139 // 140 // Export C numeric/string defines as Go constants by prefixing the define's 141 // name with `prefix`. 142 // 143 // Name conflicts are resolved by adding a numeric suffix. 144 // 145 // Exporting C enum constants 146 // 147 // -export-enums "" 148 // 149 // Export C enum constants as Go constants by capitalizing the first letter of 150 // the enum constant name. 151 // 152 // -export-enums prefix 153 // 154 // Export C enum constants as Go constants by prefixing the enum constant name 155 // with `prefix`. 156 // 157 // Name conflicts are resolved by adding a numeric suffix. 158 // 159 // Exporting C externs 160 // 161 // -export-externs "" 162 // 163 // Export C extern definitions as Go definitions by capitalizing the first 164 // letter of the definition name. 165 // 166 // -export-externs prefix 167 // 168 // Export C extern definitions as Go definitions by prefixing the definition 169 // name with `prefix`. 170 // 171 // Name conflicts are resolved by adding a numeric suffix. 172 // 173 // Exporting C struct fields 174 // 175 // -export-fields "" 176 // 177 // Export C struct fields as Go fields by capitalizing the first letter of the 178 // field name. 179 // 180 // -export-fields prefix 181 // 182 // Export C struct fields as Go fields by prefixing the field name with 183 // `prefix`. 184 // 185 // Name conflicts are resolved by adding a numeric suffix. 186 // 187 // Exporting tagged C struct and union types 188 // 189 // -export-structs "" 190 // 191 // Export tagged C struct/union types as Go types by capitalizing the first 192 // letter of the tag name. 193 // 194 // -export-structs prefix 195 // 196 // Export tagged C struct/union types as Go types by prefixing the tag name 197 // with `prefix`. 198 // 199 // Name conflicts are resolved by adding a numeric suffix. 200 // 201 // Exporting C typedefs 202 // 203 // -export-typedefs "" 204 // 205 // Export C typedefs as Go types by capitalizing the first letter of the 206 // typedef name. 207 // 208 // -export-structs prefix 209 // 210 // Export C typedefs as as Go types by prefixing the typedef name with 211 // `prefix`. 212 // 213 // Name conflicts are resolved by adding a numeric suffix. 214 // 215 // Prefixing static identifiers 216 // 217 // -static-locals-prefix prefix 218 // 219 // Prefix C static local declarators names with 'prefix'. 220 // 221 // Selecting command for target configuration 222 // 223 // -host-config-cmd command 224 // 225 // This option has the same effect as setting `CCGO_CPP=command`. 226 // 227 // Adding options to the configuration command 228 // 229 // -host-config-opts comma-separated-list 230 // 231 // The separated items of the list are added to the invocation of the 232 // configuration command. 233 // 234 // Setting the Go package name 235 // 236 // -pkgname name 237 // 238 // Set the resulting Go package name to 'name'. Defaults to `main`. 239 // 240 // Compiler scripts 241 // 242 // -script filename 243 // 244 // Ccgo does not yet have a concept of object files. All C files that are 245 // needed for producing the resulting Go file have to be compiled together and 246 // "linked" in memory. There are some problems with this approach, one of them 247 // is the situation when foo.c has to be compiled using, for example `-Dbar=42` 248 // and "linked" with baz.c that needs to be compiled with `-Dbar=314`. Or `bar` 249 // must not defined at all for baz.c, etc. 250 // 251 // A script in a named file is a CSV file. It is opened like this (error 252 // handling omitted): 253 // 254 // f, _ := os.Open(fn) 255 // r := csv.NewReader(f) 256 // r.Comment = '#' 257 // r.FieldsPerRecord = -1 258 // r.TrimLeadingSpace = true 259 // 260 // The first field of every record in the CSV file is the directory to use. 261 // The remaining fields are the arguments of the ccgo command. 262 // 263 // This way different C files can be translated using different options. The 264 // CSV file may look something like: 265 // 266 // /home/user/foo,-Dbar=42,foo.c 267 // /home/user/bar,-Dbar=314,bar.c 268 // 269 // Forcing atomic access 270 // 271 // -volatile comma-separated-list 272 // 273 // The separated items of the list are added to the list of file scope extern 274 // variables the will be accessed atomically, like if their C declarator used 275 // the 'volatile' type specifier. Currently only C scalar types of size 4 and 8 276 // bytes are supported. Other types/sizes will ignore both the volatile 277 // specifier and the -volatile option. 278 // 279 // Capturing host configuration 280 // 281 // -save-config path 282 // 283 // This option copies every header included during compilation or compile 284 // database generation to a file under the path argument. Additionally the 285 // host configuration, ie. predefined macros, include search paths, os and 286 // architecture is stored in path/config.json. 287 // 288 // When this option is used, no Go code is generated, meaning no link phase 289 // occurs and thus the memory consumption should stay low. 290 // 291 // Passing an empty string as an argument of -save-config is the same as if the 292 // option is not present at all. Possibly useful when the option set is 293 // generated in code. 294 // 295 // This option is ignored when -compiledb <path> is used. 296 // 297 // Using captured configuration 298 // 299 // --load-config path 300 // 301 // Note that this option must have the double dash prefix to distinguish it 302 // from -lfoo, the [traditional] short form of `-l foo`. 303 // 304 // This option configures the compiler using path/config.json. The include 305 // paths are adjusted to be relative to path. For example: 306 // 307 // Assume on machine A the default C preprocessor reports a system include 308 // search path "/usr/include". Running ccgo on A with -save-config /tmp/foo to 309 // compile foo.c that #includes <stdlib.h>, which is found in 310 // /usr/include/stdlib.h on the host results in 311 // 312 // - /tmp/foo/config.json having an element "/usr/include" in the SysIncludePaths array. 313 // - Host's /usr/include/stdlib.h is copied to /tmp/foo/usr/include/stdlib.h. 314 // 315 // Assume /tmp/foo from machine A will be recursively copied to machine B, that 316 // may run a different operating system and/or architecture. Let the copy be 317 // for example in /tmp/bar. Using --load-config /tmp/bar will instruct ccgo to 318 // configure its preprocessor with a system include path /tmp/bar/usr/include 319 // and thus use the original machine A stdlib.h found there. When the 320 // --load-config is used, no host configuration from a machine B cross C 321 // preprocessor/compiler is needed to transpile the foo.c source on machine B 322 // as if the compiler would be running on machine A. 323 // 324 // The particular usefulness of this mechanism is for transpiling big projects 325 // for 32 bit architectures. There the lack if ccgo having an object format and 326 // thus linking everything in RAM can need too much memory for the system to 327 // handle. The way around this is possibly to run something like 328 // 329 // $ ./configure 330 // $ ccgo -compiledb cdb.json make libfoo.a 331 // $ ccgo -save-config path config.json libfoo.a 332 // 333 // on machine A, transfer path/* to machine B and run the link phase there with 334 // eg. 335 // 336 // $ ccgo --load-config path config.json libfoo.a 337 // 338 // Note that the C sources for the project must be in the same path on both 339 // machines because the compile database stores absolute paths. It might be 340 // convenient to put the sources in path/src, the config in path/config, for 341 // example, and transfer the [archive of] path/ to the same directory on the 342 // second machine. That also solves the issue when ./configure generates files 343 // and the result differs per operating system or architecture. 344 // 345 // Passing an empty string as an argument of -load-config is the same as if the 346 // option is not present at all. Possibly useful when the option set is 347 // generated in code. 348 // 349 // Boolean options 350 // 351 // These command line options don't take arguments. 352 // 353 // Preprocessing 354 // 355 // -E 356 // 357 // When this option is present the compiler does not produce any Go files and 358 // instead prints the preprocessor output to stdout. 359 // 360 // Removing error limit 361 // 362 // -all-errors 363 // 364 // Normally only the first 10 or so errors are shown. With this option the 365 // compiler will show all errors. 366 // 367 // Compiling header files 368 // 369 // -header 370 // 371 // Using this option suppresses producing of any function definitions. This is 372 // possibly useful for producing Go files from C header files. 373 // 374 // Including function signatures with -header. 375 // 376 // -func-sig 377 // 378 // Add this option to include fucntion signature when compiling headers (using -header). 379 // 380 // Suppressing C stdlib include search paths 381 // 382 // -nostdinc 383 // 384 // This option disables the default C include search paths. 385 // 386 // Suppressing runtime import 387 // 388 // -nostdlib 389 // 390 // This option disables importing of the runtime library by the resulting Go 391 // code. 392 // 393 // Output information about pinned declarators 394 // 395 // -trace-pinning 396 // 397 // This option will print the positions and names of local declarators that are 398 // being pinned. 399 // 400 // Obtaining version information 401 // 402 // -version 403 // 404 // Ignore all other options, print version and exit. 405 // 406 // Verbose compile DB generation 407 // 408 // -verbose-compiledb 409 // 410 // Enable verbose output when -compiledb is present. 411 // 412 // Ignore undefined functions 413 // 414 // -ignore-undefined 415 // 416 // This option tells the linker to not insist on finding definitions for 417 // declarators that are not implicitly declared and used - but not defined. 418 // This might be useful when the intent is to define the missing function in Go 419 // functions manually. Name conflict resolution for such declarator names may 420 // or may not be applied. 421 // 422 // Ignoring unsupported aligmnent 423 // 424 // -ignore-unsupported-alignment 425 // 426 // This option tells the compiler to not complain about alignments that Go 427 // cannot support. 428 // 429 // Tracing included files 430 // 431 // -trace-included-files 432 // 433 // This option outputs the path names of all included files. 434 // 435 // This option is ignored when -compiledb <path> is used. 436 // 437 // Undocumented options 438 // 439 // There may exist other options not listed above. Those should be considered 440 // temporary and/or unsupported and may be removed without notice. 441 // Alternatively, they may eventually get promoted to "documented" options. 442 package main // import "modernc.org/ccgo/v3" 443