CONTRIBUTING.md

Welcome

nstd not good enough? Let's make it better. This text is here to provide a formal introduction on how to contribute to the nstd codebase. The code is currently hosted on GitHub at https://github.com/RustEnthusiast/nstd. Make a clone or fork of the repository to get started.

Please note that you may need to know a bit of Rust and C before contributing.

Sections

• Adding a module
• Adding a submodule
• Adding a type
• Adding a function

Adding a module

Adding a top-level module to nstd is fairly straight forward, but requires a few tedious steps.

Create a Cargo feature for the module

The first thing you'll need to do when creating a new module is create a feature for the module. This will allow users of the framework to disable compilation of our module if their code doesn't require it.

To do this, open the Cargo.toml file and head to the [features] section. The module features are listed in alphabetical order following the default, std, capi, and link features. Place the new feature where it is appropriate.

The new feature should look something like this: {module_name} = [].

The square brackets contain any dependencies that our module requires.

Add the module header

Each top-level module needs a C header file in the include/nstd directory in the repository describing the module's API. The header file shall be named {module_name}.h. There should now be a new file located at include/nstd/{module_name}.h.

Each header file needs a header guard. nstd does not use the #pragma once directive as it is not strictly part of the C standard, so don't use this approach. Instead we will use a form of header guards that are guaranteed to work with any compiler. Header guard definitions in nstd are just a path to the file from within the include directory. The header guard should look like this:

#ifndef NSTD_{MODULE_NAME}_H
#define NSTD_{MODULE_NAME}_H
#endif

The include/nstd.h header includes all top-level headers in alphabetical order, be sure to include your header in this file.

Add the source file

You will now need to add a Rust source file that defines your module's API. Create a new Rust source file in the src directory named {module_name}.rs. Make sure to give a description of your module with a //! comment at the top of the file. Since we are creating a top-level module we will need to modify the src/lib.rs file by declaring our module in there. All other top-level modules are listed here in alphabetical order. Every top-level module must be hidden behind a feature gate, we will need to enforce that here by using Rust's cfg attribute. Place a declaration of your module where it is appropriate. The module declaration should look like this:

#[cfg(feature = "{module_name}")]
#[cfg_attr(doc_cfg, doc(cfg(feature = "{module_name}")))]
pub mod {module_name};

Update the README

This step isn't that important but it is technically required. The repo's README.md markdown file contains an alphabetically sorted list of nstd's modules along with a short description of each module. Place your module into this tree where it is appropriate.

Adding a submodule

todo!();

Adding a type

todo!();

Adding a function

todo!();