jocadbz
/
lana
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
lana/DOCS.md

408 lines
14 KiB
Markdown
Raw Blame History

# Lana Documentation
## Table of Contents
1. [Overview](#overview)
2. [Installation](#installation)
3. [Project Structure](#project-structure)
4. [Commands](#commands)
5. [Configuration](#configuration)
6. [Build Directives](#build-directives)
7. [Build Process](#build-process)
8. [Dependency Management](#dependency-management)
9. [Command Line Options](#command-line-options)
10. [Configuration File Format](#configuration-file-format)
11. [Troubleshooting](#troubleshooting)
12. [Development](#development)
## Overview
Lana is a lightweight C++ build system designed for modern C++ development. It provides a simple, fast alternative to complex tools like CMake or Make, emphasizing speed, simplicity, and self-contained project management.
Key features:
- **Automatic source discovery** in `src/` directories
- **Build directives** embedded directly in C++ source files for per-file configuration (dependencies, linking, output, flags)
- **Dependency tracking** via `#include` analysis and timestamp checking
- **Incremental builds** to recompile only changed files
- **Support for shared libraries, tools/executables, and GLSL shaders**
- **Simple global configuration** via `config.ini`
- **Cross-platform** (Linux, macOS, Windows) with parallel compilation
- **No external scripts needed**—everything is in your source files
Lana parses `// build-directive:` comments in your C++ files to handle project-specific details, while `config.ini` manages globals like compiler flags and paths.
## Installation
### Prerequisites
- V compiler (version 0.3.0 or later)
- GCC/G++ (version 7+ recommended)
- Standard C++ library
- For shaders: Vulkan SDK or shaderc (includes `glslc`)
### Building Lana
1. Clone the repository:
```bash
git clone https://github.com/yourusername/lana.git # Replace with actual repo
cd lana
```
2. Build the tool:
```bash
v . -o lana
```
3. Make executable (Linux/macOS):
```bash
chmod +x lana
```
4. Add to PATH (optional):
```bash
sudo mv lana /usr/local/bin/
```
## Project Structure
Lana expects this layout (created by `lana init`):
```
project/
├── src/ # Source files (.cpp, .cc, .cxx) with build directives
│ ├── main.cpp # Example main tool (directives at top)
│ ├── lib/ # Shared library sources
│ │ └── cli.cpp # Example shared lib (directives at top)
│ ├── tools/ # Tool/executable sources
│ │ └── example_tool.cpp # Example tool depending on lib/cli
│ └── shaders/ # GLSL shaders (.vsh, .fsh)
├── include/ # Header files (.h, .hpp)
│ └── cli.h # Example header
├── build/ # Generated: Object files (*.o), dependencies (*.d)
├── bin/ # Generated: Executables and libs
│ ├── lib/ # Shared libraries (.so/.dll)
│ ├── tools/ # Tool executables
│ └── shaders/ # Compiled shaders (.spv)
├── config.ini # Global build configuration
├── README.md # Project docs (auto-generated with directive examples)
└── .gitignore # Ignores build artifacts
```
- **Build Directives**: Add `// build-directive:` comments at the top of C++ files for per-file settings (see [Build Directives](#build-directives)).
- **Auto-Discovery**: If no directives, Lana treats files as simple tools using global config.
- **Shaders**: Place `.vsh` (vertex) and `.fsh` (fragment) files in `src/shaders/`; set `shaders_dir` in config to enable compilation.
## Commands
### Initialize Project
```bash
lana init <project_name>
```
Creates the structure above, including template C++ files **with build directives by default** (e.g., in `src/main.cpp`, `src/lib/cli.cpp`). Includes `config.ini`, `README.md` (with directive docs), and examples for shared libs/tools.
**Example:**
```bash
lana init myapp
cd myapp
# Files like src/main.cpp now have directives like:
# // build-directive: unit-name(tools/main)
# // build-directive: out(tools/main)
```
### Build Project
```bash
lana build [options]
```
Compiles sources, processes directives, builds dependency graph, and links outputs. Incremental: only rebuilds changed files.
**Options:** See [Command Line Options](#command-line-options).
**Example:**
```bash
lana build -d -v # Debug build with verbose output (shows directive parsing)
```
### Run Project
```bash
lana run [options]
```
Builds (if needed) and runs the main executable (first tool or `project_name` from config/directives).
**Example:**
```bash
lana run -O # Optimized run
```
### Clean Project
```bash
lana clean
```
Removes `build/`, `bin/`, and intermediates.
**Example:**
```bash
lana clean
```
### Help
```bash
lana --help
```
Shows commands, options, and config examples.
## Configuration
`config.ini` handles **global** settings (overridden by directives for per-file needs). Edit it in your project root.
### Basic Configuration
```ini
# Project identification
project_name = myapp
# Directory paths (relative to project root)
src_dir = src
build_dir = build
bin_dir = bin
# Build modes (mutually exclusive; CLI overrides)
debug = true
optimize = false
# Output verbosity
verbose = false
# Compiler settings (global defaults; directives can add/override)
include_dirs = include # Comma/space-separated
libraries = pthread # Comma/space-separated (global libs)
cflags = -Wall -Wextra -std=c++17
ldflags =
# Advanced
parallel_compilation = true
shaders_dir = bin/shaders # Enable shader compilation
dependencies_dir = dependencies
```
### Configuration Precedence
1. Command-line options (highest: e.g., `-d` overrides `debug=true`)
2. `config.ini`
3. Defaults (e.g., `debug=true`, compiler=`g++`)
Directives (in source files) handle per-file overrides (e.g., custom `cflags` for one unit).
## Build Directives
Lana's killer feature: Embed build instructions **directly in C++ source files** using `// build-directive:` comments. No separate scripts—keeps projects self-contained.
### How It Works
- **Parsing**: `lana build` scans sources for lines like `// build-directive: <type>(<value>)`.
- **Processing**: Builds a dependency graph; resolves build order, linking, and flags.
- **Placement**: At file top (before code). Multiple per file (one per line).
- **Fallback**: No directives? Auto-discover as simple tool using global config.
- **Output**: Verbose mode (`-v`) shows parsed units/graph.
### Syntax
```
// build-directive: <type>(<value>)
```
- `<type>`: Directive name (e.g., `unit-name`).
- `<value>`: Arguments (comma/space-separated for lists; `true/false` for bools).
### Supported Directives
- **`unit-name(<name>)`**: Unique unit ID (e.g., `"lib/cli"`, `"tools/mytool"`). Required for custom builds. Defaults to file path if omitted.
- **`depends-units(<unit1>,<unit2>,...)`**: Dependencies (other units, e.g., `"lib/utils,lib/file"`). Builds them first.
- **`link(<lib1>,<lib2>,...)`**: Libraries to link (e.g., `"utils.so,pthread,boost_system"`). Internal (Lana-built) or external.
- **`out(<path>)`**: Output relative to `bin/` (e.g., `"tools/mytool"`, `"lib/mylib"`). Defaults to unit name.
- **`cflags(<flag1> <flag2> ...)`**: Per-file compiler flags (e.g., `"-std=c++20 -fPIC"`). Appends to global `cflags`.
- **`ldflags(<flag1> <flag2> ...)`**: Per-file linker flags (e.g., `"-static -pthread"`). Appends to global `ldflags`.
- **`shared(<true|false>)`**: Build as shared lib (`.so`/`.dll`, true) or executable (false, default).
### Examples
**Simple Executable (`src/main.cpp`)**:
```cpp
// build-directive: unit-name(tools/main)
// build-directive: depends-units()
// build-directive: link()
// build-directive: out(tools/main)
#include <iostream>
int main() {
std::cout << "Hello, World!" << std::endl;
return 0;
}
```
- Builds `bin/tools/main` executable. No deps.
**Shared Library (`src/lib/cli.cpp`)**:
```cpp
// build-directive: unit-name(lib/cli)
// build-directive: depends-units()
// build-directive: link()
// build-directive: out(lib/cli)
// build-directive: shared(true)
// build-directive: cflags(-fPIC)
#include <iostream>
#include "cli.h"
namespace lana {
void print_help() { std::cout << "CLI help" << std::endl; }
}
```
- Builds `bin/lib/cli.so`. PIC for shared lib.
**Tool Depending on Shared Lib (`src/tools/mytool.cpp`)**:
```cpp
// build-directive: unit-name(tools/mytool)
// build-directive: depends-units(lib/cli)
// build-directive: link(cli.so)
// build-directive: out(tools/mytool)
// build-directive: shared(false)
// build-directive: cflags(-std=c++17)
// build-directive: ldflags(-pthread)
#include <iostream>
#include "cli.h"
int main() {
lana::print_help();
return 0;
}
```
- Depends on/builds `lib/cli` first; links `cli.so`; outputs `bin/tools/mytool`.
### Tips
- **Order**: Directives before `#include` or code.
- **Empty Values**: Use `()` for none (e.g., `depends-units()`).
- **Global Interaction**: Directives add to `config.ini` settings (e.g., global `-Wall` + per-file `-std=c++20`).
- **Shaders**: No directives needed; auto-compiles if `shaders_dir` set.
- **Legacy**: Use `[shared_libs]`/`[tools]` in config for manual lists (overrides auto-parsing).
## Build Process
1. **Parse Directives**: Scans sources for `// build-directive:`; collects into units/graph.
2. **Source Discovery**: Finds `.cpp`/`.cc`/`.cxx` in `src_dir` (recursive).
3. **Dependency Analysis**: Extracts `#include`s; builds graph from directives/timestamps.
4. **Incremental Check**: Recompiles if source/header newer than `.o` or `.d` missing.
5. **Compilation**: `g++ -c` each source to `.o` (uses global + per-file flags).
6. **Linking**: Builds shared libs/tools per directives (e.g., `g++ -shared` for libs).
7. **Shaders** (if enabled): Compiles `.vsh`/`.fsh` to `.spv` with `glslc`.
**Example Output** (`lana build -v`):
```
Parsing build directives...
Found directive for unit: lib/cli in src/lib/cli.cpp
Found directive for unit: tools/mytool in src/tools/mytool.cpp
Building dependency graph...
Build order: lib/cli -> tools/mytool
Building unit: lib/cli
Compiling src/lib/cli.cpp -> build/lib/cli.o
Linking shared library: bin/lib/cli.so
Building unit: tools/mytool
Compiling src/tools/mytool.cpp -> build/tools/mytool.o
Linking executable: bin/tools/mytool
Build completed successfully!
```
## Dependency Management
- **Include Extraction**: Parses `#include` for rebuild triggers (local/system headers).
- **Directive-Based Deps**: `depends-units()` defines unit graph; `link()` handles libs.
- **Timestamp Checks**: Rebuild if source/header > `.o` timestamp.
- **Generated `.d` Files**: Make-compatible deps (e.g., `build/main.o: src/main.cpp include/utils.hpp`).
- **Graph Resolution**: Topological sort; warns on cycles.
## Command Line Options
| Option | Description | Example |
|--------|-------------|---------|
| `-d, --debug` | Debug mode (`-g -O0`) | `lana build -d` |
| `-O, --optimize` | Optimized mode (`-O3`) | `lana build -O` |
| `-v, --verbose` | Show commands/graph | `lana build -v` |
| `-p, --parallel` | Parallel jobs | `lana build -p` |
| `-o <name>` | Output name | `lana build -o app` |
| `-I <dir>` | Include dir | `lana build -I external/` |
| `-l <lib>` | Link lib | `lana build -l pthread` |
| `--config <file>` | Custom config | `lana build --config release.ini` |
| `--shared-lib <name> <source>` | Legacy shared lib | `lana build --shared-lib cli src/lib/cli.cpp` |
| `--tool <name> <source>` | Legacy tool | `lana build --tool mytool src/tools/mytool.cpp` |
**Examples:**
```bash
lana build -d -v -p # Debug, verbose, parallel
lana run -O # Optimized run
lana build -I lib/include -l boost -l sqlite3
```
## Configuration File Format
INI-style (`config.ini`):
```ini
# Comments with #
key = value
array_key = val1, val2 # Comma/space-separated
```
**Full Example (`config.ini`)**:
```ini
[global]
project_name = myapp
src_dir = src
build_dir = build
bin_dir = bin
debug = true
optimize = false
verbose = false
parallel_compilation = true
include_dirs = include,external/include
libraries = pthread,boost_system
cflags = -Wall -Wextra -std=c++17
ldflags = -static
[shared_libs] # Legacy/manual (directives preferred)
name = cli
sources = src/lib/cli.cpp
libraries =
[tools] # Legacy/manual
name = main
sources = src/main.cpp
libraries = cli
shaders_dir = bin/shaders # Enable shaders
```
## Troubleshooting
### Common Issues
- **"No source files found"**: Check `src_dir` in config; ensure `.cpp` files exist.
- **"Failed to parse directive"**: Verify syntax (e.g., `unit-name(lib/cli)`); use `-v` for details.
- **"Dependency not found"**: Add missing `depends-units()` or build order in directives.
- **Linking errors**: Check `link()` for libs; install dev packages (e.g., `sudo apt install libpthread-dev`).
- **Shader compilation fails**: Install Vulkan SDK (`glslc`); verify `shaders_dir` in config.
- **Permission denied**: `chmod +x bin/tools/mytool`.
### Debugging Tips
- **Verbose Build**: `lana build -v` shows directive parsing, graph, and commands.
- **Check Graph**: Look for "Build order:" in verbose output.
- **Dependency Files**: Inspect `build/*.d` for include tracking.
- **Logs**: `lana build -v > build.log 2>&1`.
- **Clean Rebuild**: `lana clean && lana build -v`.
## Development
See the source code structure in the repo. To extend:
- Add directives: Update `config.BuildDirective` and `builder.build_from_directives()`.
- New features: Modify `config.v` for parsing, `builder.v` for logic.
For contributing, see [GitHub](https://github.com/yourusername/lana) (fork, branch, PR).
---
*Documentation for Lana v1.0.0*
*Last updated: 2025-09-17*
*Issues: [Issues](https://lostcave.ddnss.de/git/jocadbz/lana)*
*Contribute: [Repo](https://lostcave.ddnss.de/git/jocadbz/lana)*
Reference in New Issue View Git Blame Copy Permalink