mirror of
https://github.com/vishapoberon/vipak.git
synced 2026-04-05 20:42:26 +00:00
local build information.
This commit is contained in:
Norayr Chilingarian
parent
c4ccd026ae
commit
ae9b05408c
2 changed files with 387 additions and 6 deletions
385
local_build.md
Normal file
385
local_build.md
Normal file
|
|
@ -0,0 +1,385 @@
|
||||||
|
# Vipak Local Build System
|
||||||
|
|
||||||
|
Vipak provides a powerful local build system for Oberon projects that automatically handles dependency resolution, fetching, and compilation. This allows you to 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 Format
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
## Examples
|
||||||
|
|
||||||
|
### 1. 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"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Multiple Build Targets
|
||||||
|
|
||||||
|
Build both a main program and a test program:
|
||||||
|
|
||||||
|
```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"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"Command": "voc -m",
|
||||||
|
"File": "src/test.Mod"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Mixed Dependency Sources
|
||||||
|
|
||||||
|
Some dependencies from Git repositories, others from HTTP sources:
|
||||||
|
|
||||||
|
```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": {
|
||||||
|
"time": "0.1",
|
||||||
|
"strutilstest": "0.1"
|
||||||
|
},
|
||||||
|
"Build": [
|
||||||
|
{
|
||||||
|
"Command": "voc -m",
|
||||||
|
"File": "src/myproject.Mod"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
*Note: `time` might come from a Git repository while `strutilstest` comes from HTTP sources, depending on how they're configured in the package tree.*
|
||||||
|
|
||||||
|
### 4. 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
|
||||||
|
|
||||||
|
### Getting Help
|
||||||
|
|
||||||
|
- Check the package tree for dependency definitions
|
||||||
|
- Verify dependency versions are available
|
||||||
|
- Ensure all required tools (`voc`, `git`) are installed
|
||||||
|
- Check network connectivity for HTTP/Git downloads
|
||||||
|
|
||||||
|
## Advanced Features
|
||||||
|
|
||||||
|
### Package Tree Integration
|
||||||
|
|
||||||
|
Vipak integrates with the global package tree for dependency resolution. Dependencies are resolved from:
|
||||||
|
|
||||||
|
1. **Local package tree** - `~/.vipak/vipatsar/`
|
||||||
|
2. **Remote package tree** - Default: https://codeberg.org/vishapoberon/vipatsar
|
||||||
|
|
||||||
|
### 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.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Contributing
|
||||||
|
|
||||||
|
To contribute to vipak or report issues, visit: https://codeberg.org/vishapoberon/vipak
|
||||||
|
|
@ -43,13 +43,9 @@ some examples:
|
||||||
|
|
||||||
`vipak -p irc_bot -P /tmp/coolprefix -t /tmp/myothertree` — the same, but the dependency resolution will be conducted by using custom package description tree.
|
`vipak -p irc_bot -P /tmp/coolprefix -t /tmp/myothertree` — the same, but the dependency resolution will be conducted by using custom package description tree.
|
||||||
|
|
||||||
todo
|
local project builds
|
||||||
====
|
====
|
||||||
|
|
||||||
json parser can be improved. it does not contain lists yet.
|
see in details [here](local_build.md)
|
||||||
|
|
||||||
though we have http module, only git downloads are currently supported by using external git tool.
|
|
||||||
|
|
||||||
port to oberon system.
|
|
||||||
|
|
||||||
lots of other things.
|
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue