Improve docs

This commit is contained in:
Matthew Holt 2020-04-07 18:56:30 -06:00
parent 1095882d94
commit 97dd3289b0
No known key found for this signature in database
GPG key ID: 2A349DD577D586A5
2 changed files with 72 additions and 62 deletions

132
README.md
View file

@ -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. 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 ## Requirements
@ -13,6 +17,67 @@ Supports Caddy 2 and up.
- Go modules enabled - 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 ## Library usage
```go ```go
@ -20,8 +85,8 @@ builder := xcaddy.Builder{
CaddyVersion: "v2.0.0-rc.1", CaddyVersion: "v2.0.0-rc.1",
Plugins: []xcaddy.Dependency{ Plugins: []xcaddy.Dependency{
{ {
ModulePath: "github.com/caddyserver/nginx-adapter", ModulePath: "github.com/caddyserver/ntlm-transport",
Version: "bdbb6db7ff9ad6ceb0dcd93f89e396f6365aa5d4", Version: "v0.1.0",
}, },
}, },
} }
@ -31,61 +96,6 @@ err := builder.Build("./caddy")
Versions can be anything compatible with `go get`. 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
```
--- ---

View file

@ -126,7 +126,7 @@ func runDev(caddyVersion string, args []string) error {
} }
currentModule := strings.TrimSpace(string(out)) 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}}") cmd = exec.Command("go", "list", "-m", "-f={{.Dir}}")
out, err = cmd.Output() out, err = cmd.Output()
if err != nil { if err != nil {