mirror of
https://github.com/vishapoberon/vipak.git
synced 2026-04-05 20:42:26 +00:00
410 lines
9.4 KiB
Markdown
410 lines
9.4 KiB
Markdown
# vipak
|
|
|
|
|
|
|
|
**vipak** is a language-agnostic package manager that provides dependency management and build automation for projects. It features a flexible backend system that retrieves dependencies from package trees and supports both global package management and local project builds.
|
|
|
|
Currently, vipak uses the [vipak tree](https://codeberg.org/vishapoberon/vipatsar) as its default backend—a collection of JSON files containing package metadata, dependency information, download sources, and build instructions.
|
|
|
|
## Installation
|
|
|
|
### Requirements
|
|
- git
|
|
- gmake
|
|
- cc
|
|
- voc
|
|
|
|
### Build from Source
|
|
|
|
```bash
|
|
git clone https://codeberg.org/vishapoberon/vipak
|
|
cd vipak
|
|
gmake
|
|
```
|
|
|
|
Now you don't need `make` anymore. (:
|
|
|
|
## Basic Usage
|
|
|
|
Run `vipak --help` to see all available options.
|
|
|
|
### Package Tree Management
|
|
|
|
```bash
|
|
# Sync the default package tree to ~/.vipak/vipatsar
|
|
vipak -s
|
|
```
|
|
|
|
### Package Operations
|
|
|
|
```bash
|
|
# Show dependencies only (no download/build)
|
|
vipak -d -p irc_bot
|
|
|
|
# Resolve and fetch packages
|
|
vipak -f -p irc_bot
|
|
|
|
# Build package and dependencies (default prefix: ~/vpkLocal)
|
|
vipak -p irc_bot
|
|
|
|
# Ask for confirmation before building
|
|
vipak -a -p irc_bot
|
|
|
|
# Build with custom prefix
|
|
vipak -p irc_bot -P /tmp/coolprefix
|
|
|
|
# Use custom package tree
|
|
vipak -p irc_bot -P /tmp/coolprefix -t /tmp/myothertree
|
|
```
|
|
|
|
## Local Build System
|
|
|
|
Vipak provides a powerful local build system for projects that automatically handles dependency resolution, fetching, and compilation. Build complex projects with external dependencies using a simple `vipak --local` command.
|
|
|
|
### Quick Start
|
|
|
|
#### Initialize a New Project
|
|
|
|
```bash
|
|
vipak --init
|
|
```
|
|
|
|
This creates:
|
|
- `vipak.json` - Project configuration file
|
|
- `src/myproject.Mod` - Template Oberon module
|
|
|
|
#### Build Your Project
|
|
|
|
```bash
|
|
vipak --local
|
|
```
|
|
|
|
This will:
|
|
1. Resolve and fetch all dependencies
|
|
2. Compile dependencies in dependency order
|
|
3. Build your project sources
|
|
|
|
### Project Structure
|
|
|
|
```
|
|
myproject/
|
|
├── vipak.json # Project configuration
|
|
├── src/ # Your source files
|
|
│ └── myproject.Mod
|
|
├── build/ # Build output (created automatically)
|
|
│ └── deps/ # Downloaded dependencies
|
|
└── deps.dot # Dependency graph (for visualization)
|
|
```
|
|
|
|
### vipak.json Configuration
|
|
|
|
The `vipak.json` file defines your project configuration:
|
|
|
|
```json
|
|
{
|
|
"Package": "project-name",
|
|
"Author": "Your Name",
|
|
"License": "GPL-3",
|
|
"Version": "0.1",
|
|
"Remote": {
|
|
"type": "git",
|
|
"path": "https://codeberg.org/yourname/project",
|
|
"tag": "0.1"
|
|
},
|
|
"Dependencies": {
|
|
"dependency1": "version",
|
|
"dependency2": "version"
|
|
},
|
|
"Build": [
|
|
{
|
|
"Command": "voc -m",
|
|
"File": "src/main.Mod"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
#### Required Fields
|
|
|
|
- **Package**: Project name
|
|
- **Author**: Author name
|
|
- **Version**: Project version
|
|
- **Build**: Array of build steps
|
|
|
|
#### Optional Fields
|
|
|
|
- **License**: Software license
|
|
- **Remote**: Git repository information (for publishing)
|
|
- **Dependencies**: External dependencies to fetch and build
|
|
|
|
### Configuration Examples
|
|
|
|
#### Simple Project with Git Dependencies
|
|
|
|
```json
|
|
{
|
|
"Package": "myproject",
|
|
"Author": "Your Name",
|
|
"License": "GPL-3",
|
|
"Version": "0.1",
|
|
"Remote": {
|
|
"type": "git",
|
|
"path": "https://codeberg.org/yourname/myproject",
|
|
"tag": "0.1"
|
|
},
|
|
"Dependencies": {
|
|
"opts": "0.1",
|
|
"Internet": "0.1"
|
|
},
|
|
"Build": [
|
|
{
|
|
"Command": "voc -m",
|
|
"File": "src/myproject.Mod"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
#### Multiple Build Targets
|
|
|
|
Build both a main program and a test program:
|
|
|
|
```json
|
|
{
|
|
"Package": "myproject",
|
|
"Author": "Your Name",
|
|
"License": "GPL-3",
|
|
"Version": "0.1",
|
|
"Dependencies": {
|
|
"opts": "0.1",
|
|
"Internet": "0.1"
|
|
},
|
|
"Build": [
|
|
{
|
|
"Command": "voc -m",
|
|
"File": "src/myproject.Mod"
|
|
},
|
|
{
|
|
"Command": "voc -m",
|
|
"File": "src/test.Mod"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
#### Library Project (No Executable)
|
|
|
|
For projects that only build library modules:
|
|
|
|
```json
|
|
{
|
|
"Package": "mylib",
|
|
"Author": "Your Name",
|
|
"License": "MIT",
|
|
"Version": "0.2",
|
|
"Build": [
|
|
{
|
|
"Command": "voc -s",
|
|
"File": "src/MyLib.Mod"
|
|
},
|
|
{
|
|
"Command": "voc -s",
|
|
"File": "src/MyLibUtils.Mod"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Build Commands
|
|
|
|
#### Common voc Options
|
|
|
|
- `voc -m file.Mod` - Compile main program (creates executable)
|
|
- `voc -s file.Mod` - Compile library module (creates .sym file)
|
|
- `voc -C file.Mod` - Compile to object file only
|
|
|
|
#### Custom Build Commands
|
|
|
|
You can use any build command, not just `voc`:
|
|
|
|
```json
|
|
"Build": [
|
|
{
|
|
"Command": "make",
|
|
"File": "Makefile"
|
|
},
|
|
{
|
|
"Command": "cp src/config.txt",
|
|
"File": "config/default.txt"
|
|
}
|
|
]
|
|
```
|
|
|
|
### Dependency Resolution
|
|
|
|
Vipak automatically:
|
|
|
|
1. **Resolves transitive dependencies** - If A depends on B, and B depends on C, all three are built
|
|
2. **Handles dependency order** - Builds dependencies before dependents
|
|
3. **Avoids duplicates** - Each dependency is built only once
|
|
4. **Supports multiple sources** - Git repositories, HTTP/HTTPS file downloads
|
|
5. **Creates build graph** - Generates `deps.dot` for visualization
|
|
|
|
#### Viewing Dependency Graph
|
|
|
|
```bash
|
|
# Generate PNG image of dependency graph
|
|
dot -Tpng deps.dot > deps.png
|
|
```
|
|
|
|
### Build Process
|
|
|
|
When you run `vipak --local`:
|
|
|
|
1. **Parse vipak.json** - Read project configuration
|
|
2. **Resolve dependencies** - Build complete dependency tree
|
|
3. **Create build directory** - `build/` for outputs
|
|
4. **Fetch dependencies** - Download from Git/HTTP sources
|
|
5. **Build dependencies** - Compile in correct order
|
|
6. **Build project** - Compile your source files
|
|
|
|
#### Build Output
|
|
|
|
```
|
|
myproject/
|
|
├── build/
|
|
│ ├── deps/ # Dependency sources
|
|
│ │ └── domain.com/project/
|
|
│ │ └── src/
|
|
│ ├── myproject # Your executable
|
|
│ └── *.sym # Symbol files
|
|
└── deps.dot # Dependency graph
|
|
```
|
|
|
|
### Example Usage Session
|
|
|
|
```bash
|
|
# Initialize new project
|
|
$ vipak --init
|
|
Project initialized! You can now:
|
|
1. Edit src/myproject.Mod with your code
|
|
2. Edit vipak.json to configure build settings
|
|
3. Run 'vipak --local' to build the project
|
|
|
|
# Edit your source file
|
|
$ vim src/myproject.Mod
|
|
|
|
# Build the project
|
|
$ vipak --local
|
|
Building local project from: vipak.json
|
|
Building project: myproject v0.1
|
|
Created build directory: build
|
|
|
|
resolving dependencies for local project...
|
|
Found 2 direct dependencies
|
|
Resolving: opts
|
|
Resolving: Internet
|
|
done! (:
|
|
|
|
dependency graph:
|
|
-----------------
|
|
digraph dependencies {
|
|
opts -> strutils
|
|
Internet -> strutils
|
|
}
|
|
-----------------
|
|
|
|
dependencies will be installed in the following order:
|
|
strutils
|
|
opts
|
|
Internet
|
|
|
|
Fetching: strutils
|
|
*** GIT: Cloning to: 'build/deps/codeberg.org/vishapoberon/strutils'
|
|
*** GIT: Clone successful
|
|
Building dependency: strutils
|
|
Build successful
|
|
|
|
Fetching: opts
|
|
*** GIT: Cloning to: 'build/deps/codeberg.org/vishapoberon/opts'
|
|
*** GIT: Clone successful
|
|
Building dependency: opts
|
|
Build successful
|
|
|
|
Fetching: Internet
|
|
*** HTTP: fetchFiles called
|
|
getting http://example.com/Internet.Mod
|
|
Build successful
|
|
|
|
All dependencies processed!
|
|
Building project: myproject
|
|
Executing: voc -m ../src/myproject.Mod
|
|
../src/myproject.Mod Compiling myproject. Main program. 608 chars.
|
|
Build completed successfully!
|
|
|
|
# Run your program
|
|
$ ./build/myproject
|
|
Hello from myproject!
|
|
This project was built using vipak --local
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
**"symbol file of imported module not found"**
|
|
- Dependency wasn't built successfully
|
|
- Check dependency is listed in vipak.json
|
|
- Verify dependency exists in package tree
|
|
|
|
**"Failed to change to build directory"**
|
|
- Build directory creation failed
|
|
- Check file permissions
|
|
- Ensure sufficient disk space
|
|
|
|
**"Warning: Build failed with code: X"**
|
|
- Dependency compilation failed
|
|
- Check dependency source code
|
|
- Verify voc can compile the dependency
|
|
|
|
### Debug Tips
|
|
|
|
1. **Check dependency graph**: Use `dot -Tpng deps.dot > deps.png`
|
|
2. **Verify downloads**: Look in `build/deps/` for source files
|
|
3. **Test dependencies manually**: Try building dependencies with `voc` directly
|
|
4. **Check build order**: Dependencies should build before your project
|
|
|
|
## Advanced Features
|
|
|
|
### Package Tree Integration
|
|
|
|
Vipak integrates with the global package tree for dependency resolution. Dependencies are resolved from:
|
|
|
|
1. **Default package tree** - `~/.vipak/vipatsar/`
|
|
2. **Custom package tree** - by using `-t` option.
|
|
3. **Project vipak.json** - when building local project.
|
|
|
|
### Custom Package Trees
|
|
|
|
You can override the package tree location:
|
|
|
|
```bash
|
|
vipak --tree /path/to/custom/tree --local
|
|
```
|
|
|
|
### Offline Builds
|
|
|
|
Once dependencies are downloaded to `build/deps/`, builds work offline. Delete the build directory to force re-downloading dependencies.
|
|
|
|
### Not implemented
|
|
|
|
vipak currently doesn't care about package versions.
|
|
It can check `md5` sums of downloaded files. But package version information is ignored for now.
|
|
|
|
## Contributing
|
|
|
|
To contribute to vipak or report issues, visit: https://codeberg.org/vishapoberon/vipak
|
|
|
|
---
|
|
|
|
*vipak - making dependency management simple and language-agnostic*
|