HACKING.md

Quickstart

1. Clone with submodules and install dependencies:

$ git clone --recurse-submodules https://github.com/greenfork/nimraylib_now
$ cd nimraylib_now
$ nimble install --depsOnly
$ nimble install c2nim
$ nimble develop

2. Open and modify src/convert_c_to_nim.nim file
3. Run nimble convert
4. Check the changes git diff
5. Run testing suite nimble testExamples
6. Commit the changes

Please use NEP1 style guide for the code.

How wrapping works

Wrapper is generated in fully reproducible fashion. Directories src/nimraylib_now/ and src/csources/ are recursively removed before each generation.

nimble convert task generates bindings by running the following scripts:

src/common_files_setup.nim

Removes src/nimraylib_now/ directory and re-creates it with the common files used in all binding variations.

src/prepare_build_files.nim

Removes build/ directory and re-populates it with all the necessary files for building, optionally performing name mangling of C sources.

src/convert_c_to_nim.nim

Performs the following tasks:

1. Modify C header files (preprocessing)
2. Run c2nim on modified C header files (processing)
3. Modify resulting Nim files (postprocessing)
4. Copy modified Nim files to release Nim files

Since every step is done automatically, updating to the next version should be a comparatively easy task.

What's up with name mangling?

There are 2 versions of bindings: mangled and not mangled. "Mangled" means that some original names are changed, in this case some of C names have additional prefix NmrlbNow_. But later we still use same name in Nim. Mangled sources are used only for static building and generated by passing -d:nimraylib_now_mangle to build scripts in nimble task.

Why and how?

There're name collisions when compiling on Windows, see the issue. In order to fix it we patch conflicting names from the original Raylib C sources and copy everything to src/csources/raylib_mangled/ to be later used for static building. Then we generate 2 bindings: for original C sources and for mangled C sources, removing the prefix NmrlbNow_ from the mangled sources, so we have identical Nim bindings in both cases. Finally we decide which bindings to use by looking at Nim compilation flags. Static build uses mangled C sources for all platforms, not just on Windows, just because it works and it is easier to support it.

How to update this library

$ git clone --recurse-submodules --shallow-submodules https://github.com/greenfork/nimraylib_now
$ cd nimraylib_now
$ nimble install --depsOnly
$ nimble install c2nim
$ git checkout master
$ cat .gitmodules  # let's see which submodules might need updating
# For every submodule do the following; here we will only do it for "raylib"
$ cd raylib
$ git pull
$ git fetch --tags
$ git tag --list
# Here you can choose any desired version or just stay at latest master
$ git checkout 3.5.0
$ cd ..
$ nimble convert
$ git diff  # review changes
$ nimble testExamples  # make sure every example still compiles
# Edit nimraylib_now.nimble file and change version according to [semver]
# Assume that the edited version is now 1.2.0
$ git commit --all --verbose
$ git tag -a v1.2.0  # version 1.2.0 is from nimble file earlier
$ git push --all
$ git push --tags

Notes on updating

Aliases of deprecated values

Look fore new const in generated Nim file, they are translated from C #define and usually are for deprecated names. Some of these deprecated names include enum values and can't be written in Nim because Nim uses typed enums. In this case just add them to ignoreDefines array in converter script. If desired, any not enum values can be equivalently translated from C using template.

Changed const/enum prefixes

When there's a diff related to the name changed across many enum values, it is likely that their prefix was changed. Look for # prefix CAMERA_ declarations used by c2nim in converter script and see if it needs to be changed, for example to # prefix CAMERA_TYPE_. The diff should help to guess what was changed git diff src/nimraylib_now/raylib.nim.