github.com/gotranspile/cxgo@v0.3.8-0.20240118201721-29871598a6a2/README.md (about)

     1  # C to Go translator
     2  
     3  [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/gotranspile/cxgo/master/LICENSE)
     4  [![Gitter](https://badges.gitter.im/gotranspile/community.svg)](https://gitter.im/gotranspile/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
     5  [![GoDoc](https://godoc.org/github.com/gotranspile/cxgo?status.svg)](https://godoc.org/github.com/gotranspile/cxgo)
     6  
     7  CxGo is a tool for translating C source code to Go (aka transpiler, source-to-source compiler).
     8  
     9  It uses [cc](https://modernc.org/cc/v3) for preprocessing and parsing C (no clang/gcc dependencies!) and
    10  a custom type-checker and AST translation layer to make the best output possible.
    11  
    12  The only requirement is: C code **must compile** with `cxgo`, including headers.
    13  
    14  Having said that, `cxgo` uses a few tricks to make this process easier.
    15  
    16  **TL;DR for the [project goals](CONTRIBUTING.md#project-goals-and-principles):**
    17  
    18  1. Implement a practical C to Go translator ([no C++](https://github.com/gotranspile/cxgo/issues/1) for now).
    19  2. Keep the output program code correct.
    20  3. Make the generated code human-readable and as idiomatic as possible.
    21  4. Make it easy to use and customize.
    22  
    23  Check the [FAQ](FAQ.md) for more common question about the project.
    24  
    25  ## Status
    26  
    27  The project is **experimental**! Do not rely on it in production and other sensitive environments!
    28  
    29  Although it was successfully tested on multiple projects, it might _change the behavior_ of the code due to yet unknown bugs.
    30  
    31  **Compiler test results:**
    32  
    33  - TCC: 62/89 (70%)
    34  - GCC: 783/1236 (63%)
    35  
    36  **Transpiled projects:**
    37  
    38  - [Potrace](./examples/potrace) (image vectorization library)
    39  - [PortableGL](https://github.com/TotallyGamerJet/pgl) (OpenGL 3.x implementation)
    40  - [Physac](https://github.com/koteyur/physac-go) (2D physics engine)
    41  
    42  ## Installation
    43  
    44  ```bash
    45  go install github.com/gotranspile/cxgo/cmd/cxgo@latest
    46  ```
    47  
    48  or download the [latest release](https://github.com/gotranspile/cxgo/releases/latest) from Github.
    49  
    50  ## How to use
    51  
    52  The fastest way to try it is:
    53  
    54  ```bash
    55  cxgo file main.c
    56  ```
    57  
    58  For more details, check our [examples](./examples/README.md) section.
    59  
    60  It will guide you through basic usage patterns as well as a more advanced ones (on real-world projects).
    61  
    62  You may also check [FAQ](FAQ.md) if you have any issues.
    63  
    64  ## Caveats
    65  
    66  The following C features are currently accepted by `cxgo`, but may be implemented partially or not implemented at all:
    67  
    68  - preserving comments from C code ([#2](https://github.com/gotranspile/cxgo/issues/2))
    69  - `static` ([#4](https://github.com/gotranspile/cxgo/issues/4))
    70  - `auto` ([#5](https://github.com/gotranspile/cxgo/issues/5))
    71  - bitfields ([#6](https://github.com/gotranspile/cxgo/issues/6))
    72  - `union` with C-identical data layout ([#7](https://github.com/gotranspile/cxgo/issues/7))
    73  - `packed` structs ([#8](https://github.com/gotranspile/cxgo/issues/8))
    74  - `asm`
    75  - `case` in weird places ([#9](https://github.com/gotranspile/cxgo/issues/9))
    76  - `goto` forbidden by Go (there is a [workaround](docs/config.md#identsflatten), though, see [#10](https://github.com/gotranspile/cxgo/issues/10))
    77  - label variables ([#11](https://github.com/gotranspile/cxgo/issues/11))
    78  - thread local storage ([#12](https://github.com/gotranspile/cxgo/issues/12))
    79  - `setjmp` (will compile, but panics at runtime)
    80  - some stdlib functions and types are missing ([good first issue!](CONTRIBUTING.md#adding-a-new-known-header))
    81  - deep type inference (when converting to Go string/slices)
    82  - considering multiple `#ifdef` paths for different OS/envs
    83  
    84  ## Community
    85  
    86  Join our [community](COMMUNITY.md)! We'd like to hear back from you!
    87  
    88  ## Contributing
    89  
    90  See [CONTRIBUTING](CONTRIBUTING.md).
    91  
    92  ## License
    93  
    94  [MIT](LICENSE)