mirror of
https://github.com/caddyserver/xcaddy.git
synced 2024-11-03 07:50:30 +00:00
Improve docs
This commit is contained in:
Matthew Holt
parent
1095882d94
commit
97dd3289b0
2 changed files with 72 additions and 62 deletions
132
README.md
132
README.md
|
|
@ -1,11 +1,15 @@
|
|||
Custom Caddy Builder
|
||||
====================
|
||||
`xcaddy` - Custom Caddy Builder
|
||||
===============================
|
||||
|
||||
This package and associated CLI tool make it easy to perform custom builds of the [Caddy Web Server](https://github.com/caddyserver/caddy).
|
||||
This command line tool and associated Go package makes it easy to make custom builds of the [Caddy Web Server](https://github.com/caddyserver/caddy).
|
||||
|
||||
It is used heavily by Caddy plugin developers as well as anyone who wishes to make custom `caddy` binaries (with or without plugins).
|
||||
|
||||
Supports Caddy 2 and up.
|
||||
|
||||
⚠️ Still in early development. Works; but no guarantees and prone to changes at this point. Stay updated and please submit feedback!
|
||||
⚠️ Still in development.
|
||||
|
||||
Stay updated, be aware of changes, and please submit feedback! Thanks!
|
||||
|
||||
## Requirements
|
||||
|
||||
|
|
@ -13,6 +17,67 @@ Supports Caddy 2 and up.
|
|||
- Go modules enabled
|
||||
|
||||
|
||||
## Command usage
|
||||
|
||||
The `xcaddy` command has two primary uses:
|
||||
|
||||
- Compile custom `caddy` binaries
|
||||
- A replacement for `go run` while developing Caddy plugins
|
||||
|
||||
Install the `xcaddy` command with:
|
||||
|
||||
```bash
|
||||
$ go get -u github.com/caddyserver/xcaddy/cmd/xcaddy
|
||||
```
|
||||
|
||||
|
||||
### Custom builds
|
||||
|
||||
Syntax:
|
||||
|
||||
```
|
||||
$ xcaddy build <caddy_version>
|
||||
[--output <file>]
|
||||
[--with <module[@version]>...]
|
||||
```
|
||||
|
||||
- `<caddy_version>` is the core Caddy version to build (required, for now).
|
||||
- `--output` changes the output file.
|
||||
- `--with` can be used multiple times to add plugins by specifying the Go module name and optionally its version, similar to `go get`.
|
||||
|
||||
For example:
|
||||
|
||||
```bash
|
||||
$ xcaddy build v2.0.0-rc.1 \
|
||||
--with github.com/caddyserver/ntlm-transport@v0.1.0
|
||||
```
|
||||
|
||||
### For plugin development
|
||||
|
||||
If you run `xcaddy` from within the folder of the Caddy plugin you're working on without the `build` subcommand described above, it will build Caddy with your current module and run it, as if you manually plugged it in and ran `go run`.
|
||||
|
||||
The binary will be built and run from the current directory, then cleaned up.
|
||||
|
||||
The current working directory must be inside an initialized Go module.
|
||||
|
||||
Syntax:
|
||||
|
||||
```
|
||||
$ xcaddy <args...>
|
||||
```
|
||||
- `<args...>` are passed through to the `caddy` command.
|
||||
|
||||
For example:
|
||||
|
||||
```bash
|
||||
$ xcaddy list-modules
|
||||
$ xcaddy run
|
||||
$ xcaddy run --config caddy.json
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
## Library usage
|
||||
|
||||
```go
|
||||
|
|
@ -20,8 +85,8 @@ builder := xcaddy.Builder{
|
|||
CaddyVersion: "v2.0.0-rc.1",
|
||||
Plugins: []xcaddy.Dependency{
|
||||
{
|
||||
ModulePath: "github.com/caddyserver/nginx-adapter",
|
||||
Version: "bdbb6db7ff9ad6ceb0dcd93f89e396f6365aa5d4",
|
||||
ModulePath: "github.com/caddyserver/ntlm-transport",
|
||||
Version: "v0.1.0",
|
||||
},
|
||||
},
|
||||
}
|
||||
|
|
@ -31,61 +96,6 @@ err := builder.Build("./caddy")
|
|||
Versions can be anything compatible with `go get`.
|
||||
|
||||
|
||||
## CLI usage
|
||||
|
||||
The CLI can be used both to make custom builds of Caddy, but also as a replacement for `go run` while developing Caddy plugins.
|
||||
|
||||
### Download
|
||||
|
||||
```
|
||||
go get -u github.com/caddyserver/xcaddy/cmd/xcaddy
|
||||
```
|
||||
|
||||
### For custom builds
|
||||
|
||||
Syntax:
|
||||
|
||||
```
|
||||
xcaddy build <version>
|
||||
[--output <file>]
|
||||
[--with <module[@version]>...]
|
||||
```
|
||||
|
||||
Where:
|
||||
|
||||
- `--version` is the core Caddy version to build (required, for now).
|
||||
- `--output` changes the output file.
|
||||
- `--with` can be used multiple times to add plugins by specifying the module name and optionally its version, in a way similar to `go get`.
|
||||
|
||||
For example:
|
||||
|
||||
```bash
|
||||
$ xcaddy build v2.0.0-rc.1 \
|
||||
--with github.com/caddyserver/nginx-adapter@bdbb6db7ff9ad6ceb0dcd93f89e396f6365aa5d4
|
||||
```
|
||||
|
||||
### For plugin development
|
||||
|
||||
If you run `xcaddy` from within the folder of the Caddy plugin you're working on without the `build` subcommand, it will build Caddy with your current module and run it, similar to if you manually plugged it in and ran `go run`.
|
||||
|
||||
The binary will be built, run from the current directory, then cleaned up.
|
||||
|
||||
Syntax:
|
||||
|
||||
```
|
||||
xcaddy <args...>
|
||||
```
|
||||
|
||||
Where:
|
||||
|
||||
- `<args...>` are passed through to the `caddy` command.
|
||||
|
||||
For example:
|
||||
|
||||
```bash
|
||||
$ xcaddy list-modules
|
||||
$ xcaddy run --config caddy.json
|
||||
```
|
||||
|
||||
|
||||
---
|
||||
|
|
|
|||
|
|
@ -126,7 +126,7 @@ func runDev(caddyVersion string, args []string) error {
|
|||
}
|
||||
currentModule := strings.TrimSpace(string(out))
|
||||
|
||||
// get its root directory
|
||||
// get the root directory of the main module
|
||||
cmd = exec.Command("go", "list", "-m", "-f={{.Dir}}")
|
||||
out, err = cmd.Output()
|
||||
if err != nil {
|
||||
|
|
|
|||
Loading…
Reference in a new issue