shogun-ninja-gen 0.0.1
A Ninja file generator designed to facilitate very simple, very fast C/C++ compilation for projects fitting a rigid but widely applicable build sequence.
License: MIT

# shogun

**shogun** is a CLI [Ninja](https://ninja-build.org/) file generator written in
Python. It is designed specifically to facilitate very simple, very fast setup
and configuration of projects compiled with gcc/g++ that use exactly the following
build sequence:

1. Individually build ___n___ *.o files from a list of source C, C++ and/or
    assembly files
2. Perform linking with `gcc <ld flags> <1st built file> <2nd built file> ... <nth build file>`

This rigidity to the build sequence allows shogun to be provided with very little
initial information in order to generate a build.ninja file, making
setting up a new project and making tweaks to it during development a trivial process.
For the same reason, however, shogun + ninja will not form a viable build
toolchain for all projects, and users desiring more flexbility should look
elsewhere.

Features:

- semi-automated location and indexing of:
  - Source files (.c, .cpp, etc.)
  - Source assembly files (.s)
  - Include paths (-Ipath/to/folder)
  - linker script (cross-compiled programs)
- Project configuration file uses readable INI file format
- CLI interface with options including:
  - Running Ninja automatically after creating build.ninja file with `shogun -b`
  - Generating a blank shogun.ini file with `shogun -g`
  - Defining a command in the project configuration file that can be executed with
    the shortcut `shogun -x`
- Option to generate a .ccls file with include paths and target/language information filled
  - only supports C at the moment

## Installation

Ninja is, of course, required to actually run the build.ninja script that shogun
will generate. The instructions here will just cover the installation of shogun itself.

Install shogun as a Python package manually (it is packaged with setuptools) as follows:

Run `git clone https://github.com/branalba/shogun.git` from your desired folder to
clone shogun onto your machine. `cd` into the repository and create a virtual
environment (it is recommended to stick to virtual environments for use of
shogun at this stage in its development). Finally, run `pip install -e .` within
the virtual environment. This will make the `shogun` terminal command available
so long as the virtual environment is activated.

## Usage

shogun should always be run from the root directory of your project (i.e.,
where you would generally place a Makefile). First, a file titled 'shogun.ini'
needs to be placed in the directory with the minimum following contents:

```bash
[Project]

# the project name will also be the name of the executable generated by Ninja
# required
proj-name = <project name>

# directory to place build files into, with respect to the project root
# required
build-dir = <build directory>

# the prefix to gcc/g++ commands (i.e., arm-none-eabi- for cross-compiled ARM programs)
# optional
prefix = <build-prefix>
```

shogun locates and imports source files by searching for files titled '.subdir.txt'
top-down starting from the project root. There are two actions taken upon discovering
such a file:

1. The folder that contains the file is searched for header files (*.h). If any are
discovered, the relative path to the folder is appended internally to the list of
include paths.
2. The file itself is parsed. The contents of each line are compared to the
files in that folder. If a match is found, the path to that file is appended
internally to the list of source files, linker scripts, or assembly files
depending on the file extension.

As such, in addition to the `shogun.ini` file the user may place a file titled
`.subdir.txt` in each project subdirectory containing source or header files they
wish to be compiled. In the case of source files or linker scripts, simply write
the name of the desired files, one per line, in the appropriate .subdir.txt file.
At this point, simply run `shogun` from the project root to generate build.ninja.

A 'prepped' example project has been provided with the repository to show what a
simple setup looks like.

Flags, source/header files, etc. may also be defined in the config file but this functionality is
not 100% complete yet. Two milestones on the roadmap include:

1. Changing the program flow so that indexed source/header files are simply appended to a section in
the config file, and the config file will then always be directly used to generate the build.ninja file.
2. Allowing the user to import config files in addition to the main project one, primarily so that flags/sources
that may be common to multiple projects (i.e., a Cortex-M config, config for a single microcontroller, etc.)

## License

Copyright © 2021 Brandon Alba

This repository is under the [MIT License](https://opensource.org/licenses/MIT)