github.com/gotranspile/cxgo@v0.3.7/docs/quirks.md (about)

     1  # C quirks
     2  
     3  This is an (incomplete) list of C quirks and current solutions for them in `cxgo`.
     4  
     5  ## Compilation and preprocessing
     6  
     7  ### `#define` instead of `const`
     8  
     9  Due to C being C, `const` is not really a constant declaration. Because of this, most project define constants with
    10  the preprocessor directives like `#define`.
    11  
    12  Unfortunately, `cxgo` lets the preprocessor replace all those constant with underlying values.
    13  
    14  This must be fixed at some point.
    15  
    16  ### Comments
    17  
    18  Comments are usually discarded by the preprocessor.
    19  
    20  Due to this, `cxgo` drops all comments for now.
    21  
    22  This must be fixed at some point.
    23  
    24  ### `#include` concatenating files
    25  
    26  In C each file is processed individually with all included files concatenated together.
    27  
    28  Thanks to information exposed by `cc`, `cxgo` can track the source file of each declaration.
    29  During translation, it tracks what file is currently active and emits only declarations from that file.
    30  
    31  ### `.c` and `.h` files
    32  
    33  `cxgo` considers `.c` and `.h` files as a one unit and will automatically merge declarations from both.
    34  
    35  ### Different included file content with `#ifdef`
    36  
    37  `cxgo` assumes that the user will configure all project-specific `#define` switches on his own.
    38  
    39  However, there is a potential to manipulate a platform-related `#define` directives that are currently emulated by `cxgo`.
    40  We could potentially translate the same file under different OS/arch combinations and compare the resulting code.
    41  All differences can be placed into separate Go files with `+build` directives.
    42  
    43  ### Private fields with incorrect headers
    44  
    45  Some projects define the same struct type differently in public and private header files.
    46  
    47  For now `cxgo` ignores this and lets the user control what to do in this case.
    48  
    49  We can be smarter here and guess a private-public struct pair based on names or function signatures. We can then properly
    50  merge those structs and set private-public field names accordingly in Go.
    51  
    52  ### Different stdlib headers
    53  
    54  Each platform may have different stdlib headers. They might also be located in different places on different distros.
    55  
    56  To solve this, `cxgo` emulates a virtual include file system at `/_cxgo_overrides`, which contain customized C stdlib
    57  headers bundled into `cxgo`.
    58  
    59  It serves two purposes: provides a zero-config experience for common use cases and allows `cxgo` to implement C stdlib
    60  differently and adapt it to the needs of Go.