Brandon Lucas
cda2e9213a
- JS_WASM_BACKEND_PLAN: Mark phases 1-5 complete, deprioritize WASM - LANGUAGE_COMPARISON: Update package manager status - OVERVIEW: Add completed features list - ROADMAP: Mark JS backend and package manager complete - Add PACKAGES.md documenting the package system Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
177 lines
3.6 KiB
Markdown
177 lines
3.6 KiB
Markdown
# Lux Package System
|
|
|
|
Lux includes a built-in package manager for managing dependencies.
|
|
|
|
## Quick Start
|
|
|
|
### Initialize a Project
|
|
|
|
```bash
|
|
# Create a new project directory
|
|
lux init my-project
|
|
cd my-project
|
|
|
|
# Or initialize in an existing directory
|
|
lux pkg init
|
|
lux pkg init my-project-name
|
|
```
|
|
|
|
This creates a `lux.toml` manifest file:
|
|
|
|
```toml
|
|
[project]
|
|
name = "my-project"
|
|
version = "0.1.0"
|
|
description = "A Lux project"
|
|
|
|
[dependencies]
|
|
# Add dependencies here
|
|
```
|
|
|
|
### Adding Dependencies
|
|
|
|
```bash
|
|
# From a git repository
|
|
lux pkg add mylib --git https://github.com/user/mylib
|
|
|
|
# From a local path
|
|
lux pkg add local-lib --path ../lib
|
|
|
|
# With a specific version (for future registry support)
|
|
lux pkg add http 1.0.0
|
|
```
|
|
|
|
### Installing Dependencies
|
|
|
|
```bash
|
|
lux pkg install
|
|
```
|
|
|
|
This installs all dependencies listed in `lux.toml` to the `.lux_packages/` directory.
|
|
|
|
### Using Packages
|
|
|
|
Once installed, import packages in your Lux code:
|
|
|
|
```lux
|
|
import mylib
|
|
|
|
let result = mylib.doSomething()
|
|
```
|
|
|
|
## Commands Reference
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `lux pkg init [name]` | Initialize a lux.toml in the current directory |
|
|
| `lux pkg install` | Install all dependencies from lux.toml |
|
|
| `lux pkg add <pkg>` | Add a dependency |
|
|
| `lux pkg remove <pkg>` | Remove a dependency |
|
|
| `lux pkg list` | List dependencies and their status |
|
|
| `lux pkg update` | Update all dependencies |
|
|
| `lux pkg clean` | Remove installed packages |
|
|
|
|
## Dependency Sources
|
|
|
|
### Git Repository
|
|
|
|
```toml
|
|
[dependencies]
|
|
mylib = { git = "https://github.com/user/mylib" }
|
|
mylib = { git = "https://github.com/user/mylib", branch = "main" }
|
|
```
|
|
|
|
### Local Path
|
|
|
|
```toml
|
|
[dependencies]
|
|
local-lib = { path = "../local-lib" }
|
|
```
|
|
|
|
### Registry (Future)
|
|
|
|
```toml
|
|
[dependencies]
|
|
http = "1.0.0"
|
|
```
|
|
|
|
## Package Structure
|
|
|
|
A valid Lux package must have one of these entry points:
|
|
|
|
1. `lib.lux` - Main module file in package root
|
|
2. `src/lib.lux` - Main module file in src directory
|
|
|
|
Example package structure:
|
|
|
|
```
|
|
mypackage/
|
|
├── lux.toml
|
|
├── lib.lux # Entry point (option 1)
|
|
└── src/
|
|
└── lib.lux # Entry point (option 2)
|
|
```
|
|
|
|
The entry point should export public functions:
|
|
|
|
```lux
|
|
// lib.lux
|
|
pub fn helper(x: Int): Int = x * 2
|
|
|
|
pub fn process(data: String): String = {
|
|
// Implementation
|
|
data
|
|
}
|
|
```
|
|
|
|
## Project Layout
|
|
|
|
A typical Lux project looks like:
|
|
|
|
```
|
|
my-project/
|
|
├── lux.toml # Project manifest
|
|
├── src/
|
|
│ └── main.lux # Main source file
|
|
├── tests/
|
|
│ └── test.lux # Test files
|
|
└── .lux_packages/ # Installed dependencies (gitignore this)
|
|
├── mylib/
|
|
│ └── lib.lux
|
|
└── utils/
|
|
└── lib.lux
|
|
```
|
|
|
|
## Standard Library
|
|
|
|
The Lux standard library is available as a package:
|
|
|
|
```bash
|
|
lux pkg add stdlib --path /path/to/lux/stdlib
|
|
```
|
|
|
|
Or use the built-in modules directly:
|
|
|
|
```lux
|
|
// Built-in modules (always available)
|
|
import html // Type-safe HTML construction
|
|
import browser // Browser effects (Dom, Storage, Navigation)
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
1. **Add `.lux_packages/` to `.gitignore`** - Dependencies should be installed, not committed
|
|
|
|
2. **Use semantic versioning** - When publishing packages, follow semver
|
|
|
|
3. **Document your exports** - Add comments to public functions
|
|
|
|
4. **Keep packages focused** - One package should do one thing well
|
|
|
|
## Future Features
|
|
|
|
- **Package Registry** - Central repository for sharing packages
|
|
- **Version Resolution** - Automatic dependency version management
|
|
- **Lock File** - Reproducible builds with exact versions
|
|
- **Publishing** - `lux pkg publish` command
|