lana/DOCS.md

Lana Documentation

Table of Contents

1. Overview
2. Installation
3. Project Structure
4. Commands
5. Configuration
6. Build Process
7. Dependency Management
8. Command Line Options
9. Configuration File Format
10. Troubleshooting
11. Development

Overview

Lana is a lightweight C++ build system. It provides a simple alternative to complex build systems like CMake, focusing on speed, simplicity, and modern C++ development workflows.

Key features:

• Automatic source file discovery
• Dependency tracking via #include analysis
• Incremental builds with timestamp checking
• Support for debug/optimized builds
• Simple configuration via INI files
• Cross-platform (Linux, macOS, Windows)

Installation

Prerequisites

• V compiler (version 0.3.0 or later)
• GCC/G++ compiler (version 7+ recommended)
• Standard C++ library

Building Lana

1. Clone the repository:

   git clone https://github.com/yourusername/lana.git
   cd lana
   

2. Build the tool:

   v . -o lana
   

3. Make executable (Linux/macOS):

   chmod +x lana
   

4. Add to PATH (optional):

   sudo mv lana /usr/local/bin/
   

Project Structure

Lana expects a specific directory layout:

project/
├── src/              # Source files (.cpp, .cc, .cxx)
│   ├── main.cpp
│   └── utils/
│       └── helper.cpp
├── include/          # Header files (.h, .hpp)
│   ├── utils.hpp
│   └── config.hpp
├── build/            # Generated: Object files (*.o), dependencies (*.d)
├── bin/              # Generated: Executable
├── config.ini        # Build configuration
├── README.md         # Project documentation
└── .gitignore        # Git configuration

Source Files

• Lana automatically finds .cpp, .cc, and .cxx files
• Supports nested directories (recursive search)
• Header files should be in include/ or subdirectories

Build Directories

• build/ - Contains object files (.o) and dependency files (.d)
• bin/ - Contains the final executable

Commands

Initialize Project

lana init <project_name>

Creates a new project with:

• Directory structure (src/, include/, build/, bin/)
• Template main.cpp
• config.ini configuration file
• .gitignore
• README.md

Example:

lana init myapp
cd myapp

Build Project

lana build [options]

Compiles all source files and links the executable. Only rebuilds files that have changed or have newer dependencies.

Options:

• -d, --debug - Enable debug mode (default)
• -O, --optimize - Enable optimization
• -v, --verbose - Show detailed build information
• -o <name> - Set output executable name
• -I <dir> - Add include directory
• -l <lib> - Link library
• --config <file> - Use custom config file

Example:

lana build -d -v
lana build -O -I external/lib/include -l pthread

Run Project

lana run [options]

Builds the project (if needed) and executes the binary.

Example:

lana run
lana run -O  # Run with optimizations

Clean Project

lana clean

Removes all generated files:

• build/ directory (object files, dependencies)
• bin/ executable

Example:

lana clean

Help

lana --help
# or
lana -h

Shows available commands and options.

Configuration

Lana uses a simple INI-style configuration file (config.ini) in the project root.

Basic Configuration

# Project identification
project_name = myapp

# Directory paths (relative to project root)
src_dir = src
build_dir = build
bin_dir = bin

# Build modes (mutually exclusive)
debug = true
optimize = false

# Output verbosity
verbose = false

# Compiler settings
include_dirs = include,external/lib/include
libraries = pthread,boost_system
cflags = -Wall -Wextra -std=c++17
ldflags = -static

Configuration Precedence

1. Command line options (highest priority)
2. config.ini file
3. Default values (lowest priority)

Directory Configuration

You can customize directory paths:

src_dir = sources
include_dirs = headers,third_party/include
build_dir = obj
bin_dir = output

Lana will create these directories automatically during the build process.

Build Process

Compilation

1. Source Discovery: Lana recursively scans src_dir for .cpp, .cc, .cxx files
2. Dependency Analysis: Extracts #include directives from each source file
3. Incremental Build Check: Compares timestamps of source files and dependencies against object files
4. Compilation: Uses g++ to compile each source file to an object file (.o)
5. Dependency Generation: Creates .d files for each object file

Linking

1. Object Collection: Gathers all compiled object files
2. Library Linking: Includes specified libraries (-l flags)
3. Final Linking: Links all objects into the executable in bin_dir

Compiler Flags

Lana generates compiler commands with:

Debug Mode (default):

g++ -c -g -O0 -Wall -Wextra -std=c++17 -Iinclude source.cpp -o build/source.o

Optimized Mode:

g++ -c -O3 -Wall -Wextra -std=c++17 -Iinclude source.cpp -o build/source.o

Linking:

g++ -g build/*.o -lpthread -o bin/myapp

Dependency Management

Lana provides basic dependency tracking through:

Include Extraction

Lana parses C++ source files to extract #include directives:

#include "utils.hpp"        // Local header
#include <iostream>         // System header
#include "../external/lib.h" // Relative path

Dependency Rules

For each source file, Lana tracks:

• Source timestamp: When the .cpp file was last modified
• Header timestamps: When included headers were last modified
• Object timestamp: When the corresponding .o file was created

Rebuild Triggers

A source file is recompiled if:

1. The source file is newer than its object file
2. Any included header is newer than the object file
3. The object file doesn't exist
4. Dependencies change (detected via .d files)

Generated Dependencies

Lana creates .d files for make compatibility:

build/main.o: src/main.cpp include/utils.hpp
build/utils/helper.o: src/utils/helper.cpp include/utils.hpp

Command Line Options

Build Options

Option	Description	Example
-d, --debug	Enable debug symbols and no optimization	lana build -d
-O, --optimize	Enable optimization (disables debug)	lana build -O
-v, --verbose	Show detailed build commands	lana build -v
-o <name>, --output <name>	Set executable name	lana build -o myapp

Include/Library Options

Option	Description	Example
-I <dir>	Add include directory	lana build -I external/include
-l <lib>	Link library	lana build -l pthread

Configuration Options

Option	Description	Example
--config <file>	Use custom config file	lana build --config custom.ini

Examples

# Debug build with verbose output
lana build -d -v

# Optimized release build
lana build -O

# Build with external dependencies
lana build -I third_party/include -l boost_system -l sqlite3

# Custom output name
lana build -o game.exe

# Use custom config
lana build --config release.ini

Configuration File Format

The config.ini file uses a simple key-value format:

Syntax

# Comments start with #
key = value

# Arrays use comma or space separation
array_key = value1, value2, value3

Available Keys

Project Settings

Key	Type	Default	Description
project_name	string	"project"	Executable name
src_dir	string	"src"	Source directory
build_dir	string	"build"	Object files directory
bin_dir	string	"bin"	Executable directory

Build Options

Key	Type	Default	Description
debug	bool	true	Enable debug mode
optimize	bool	false	Enable optimization
verbose	bool	false	Verbose output

Compiler Settings

Key	Type	Default	Description
include_dirs	string[]	[]	Include directories (comma/space separated)
libraries	string[]	[]	Linker libraries (comma/space separated)
cflags	string[]	[]	Additional compiler flags (space separated)
ldflags	string[]	[]	Additional linker flags (space separated)

Example Configurations

Debug Configuration (debug.ini)

project_name = myapp
src_dir = src
build_dir = build
bin_dir = bin

debug = true
optimize = false
verbose = true

include_dirs = include,external/lib/include
libraries = pthread
cflags = -Wall -Wextra -std=c++17 -fPIC
ldflags = 

Release Configuration (release.ini)

project_name = myapp
src_dir = src
build_dir = build
bin_dir = bin

debug = false
optimize = true
verbose = false

include_dirs = include
libraries = pthread
cflags = -O3 -DNDEBUG -std=c++17
ldflags = -s

Troubleshooting

Common Issues

"No source files found"

Cause: No .cpp, .cc, or .cxx files in the source directory.

Solution:

1. Check src_dir in config.ini
2. Verify source files exist in the specified directory
3. Ensure files have correct extensions

"Compilation failed"

Cause: Compiler errors in source code.

Solution:

1. Use -v flag to see full compiler output
2. Check for syntax errors, missing headers, or type issues
3. Verify include paths with -I flags

"Linking failed"

Cause: Missing libraries or undefined symbols.

Solution:

1. Install required development libraries (sudo apt install libxxx-dev)
2. Add libraries with -l flag or libraries in config
3. Check library paths with -L flag if needed

"Permission denied"

Cause: Missing execute permissions on generated binary.

Solution:

chmod +x bin/myapp

Build Verbosity

Enable verbose mode to see detailed build information:

lana build -v

This shows:

• Full compiler and linker commands
• Include paths being used
• Dependency analysis results
• File timestamps

Log Files

Lana doesn't create log files by default, but you can capture output:

lana build -v > build.log 2>&1

Compiler Detection

Lana uses g++ by default. To use a different compiler:

1. Set environment variable:

   export CXX=clang++
   

2. Modify build scripts (advanced): Edit config.v to change the compiler path.

Development

Architecture

Lana consists of several modules:

lana/
├── config/          # Configuration parsing and defaults
├── builder/         # Core build logic
├── deps/            # Dependency extraction and tracking
├── runner/          # Executable execution
├── initializer/     # Project initialization
├── help/            # Help text and CLI interface
└── main.v           # Entry point

Building from Source

1. Install V:

   git clone https://github.com/vlang/v
   cd v
   make
   

2. Build Lana:

   v . -o lana
   

3. Run tests (if implemented):

   v test .
   

Adding Features

New Build Options

1. Add to config.BuildConfig struct
2. Update parse_args() in config.v
3. Modify compiler/linker command builders
4. Update help text

Custom Compilers

To support different compilers:

1. Add compiler detection in config.v
2. Create compiler-specific flag mappings
3. Update build_compiler_command() and build_linker_command()

Advanced Dependency Tracking

For more sophisticated dependency management:

1. Enhance deps.extract_dependencies() to handle:
   • Preprocessor macros
   • Template instantiations
   • Conditional includes
2. Implement dependency graph analysis
3. Add parallel build support

Contributing

1. Fork the repository
2. Create feature branch:

   git checkout -b feature/amazing-feature
   

3. Make changes and add tests
4. Commit:

   git commit -m 'Add amazing feature'
   

5. Push to branch:

   git push origin feature/amazing-feature
   

6. Create Pull Request

Code Style

• Follow V coding conventions
• Use descriptive variable names
• Keep functions small and focused
• Add comments for complex logic
• Write tests for new features

License

Lana is licensed under the MIT License. See the LICENSE file for details.

---

Documentation generated for Lana version 1.0.0 Last updated: [Current Date] Report issues: [GitHub Issues Link] Contribute: [GitHub Repository Link]