github.com/gotranspile/cxgo@v0.3.7/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  - TCC: 62/89 (70%)
    33  - GCC: 783/1236 (63%)
    34  
    35  **Transpiled projects:**
    36  - [Potrace](./examples/potrace) (image vectorization library)
    37  - [PortableGL](https://github.com/TotallyGamerJet/pgl) (OpenGL 3.x implementation)
    38  - [Physac](https://github.com/koteyur/physac-go) (2D physics engine)
    39  
    40  ## Installation
    41  
    42  ```bash
    43  go get -u github.com/gotranspile/cxgo/cmd/cxgo
    44  ```
    45  
    46  or download the [latest release](https://github.com/gotranspile/cxgo/releases/latest) from Github.
    47  
    48  ## How to use
    49  
    50  The fastest way to try it is:
    51  
    52  ```bash
    53  cxgo file main.c
    54  ```
    55  
    56  For more details, check our [examples](./examples/README.md) section.
    57  
    58  It will guide you through basic usage patterns as well as a more advanced ones (on real-world projects).
    59  
    60  You may also check [FAQ](FAQ.md) if you have any issues.
    61  
    62  ## Caveats
    63  
    64  The following C features are currently accepted by `cxgo`, but may be implemented partially or not implemented at all:
    65  
    66  - preserving comments from C code ([#2](https://github.com/gotranspile/cxgo/issues/2))
    67  - `static` ([#4](https://github.com/gotranspile/cxgo/issues/4))
    68  - `auto` ([#5](https://github.com/gotranspile/cxgo/issues/5))
    69  - bitfields ([#6](https://github.com/gotranspile/cxgo/issues/6))
    70  - `union` with C-identical data layout ([#7](https://github.com/gotranspile/cxgo/issues/7))
    71  - `packed` structs ([#8](https://github.com/gotranspile/cxgo/issues/8))
    72  - `asm`
    73  - `case` in weird places ([#9](https://github.com/gotranspile/cxgo/issues/9))
    74  - `goto` forbidden by Go (there is a [workaround](docs/config.md#identsflatten), though, see [#10](https://github.com/gotranspile/cxgo/issues/10))
    75  - label variables ([#11](https://github.com/gotranspile/cxgo/issues/11))
    76  - thread local storage ([#12](https://github.com/gotranspile/cxgo/issues/12))
    77  - `setjmp` (will compile, but panics at runtime)
    78  - some stdlib functions and types are missing ([good first issue!](CONTRIBUTING.md#adding-a-new-known-header))
    79  - deep type inference (when converting to Go string/slices)
    80  - considering multiple `#ifdef` paths for different OS/envs
    81  
    82  ## Community
    83  
    84  Join our [community](COMMUNITY.md)! We'd like to hear back from you!
    85  
    86  ## Contributing
    87  
    88  See [CONTRIBUTING](CONTRIBUTING.md).
    89  
    90  ## License
    91  
    92  [MIT](LICENSE)