Mirrors/xcaddy
1
0
Fork 0
mirror of https://github.com/caddyserver/xcaddy.git synced 2024-11-15 22:00:18 +00:00
Code Issues Projects Releases Packages Wiki Activity

Update the README as per #186 (#187)

Browse source
This commit is contained in:
Francis Lavoie 2024-05-29 18:09:42 -04:00 committed by GitHub
parent d7277dbc5d
commit dbedcb694e
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 23 additions and 7 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

30
README.md
View file

@ -73,11 +73,14 @@ $ xcaddy build [<caddy_version>]
- A commit like `a58f240d3ecbb59285303746406cab50217f8d24`
- `--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`. Module name is required, but specific version and/or local replacement are optional.
- `--replace` can be used multiple times to replace dependencies to specific forks or local replacements. Useful in development environment to fix bugs in dependencies.
- `--embed` can be used multiple times to embed directories into the built Caddy executable. The directory can be prefixed with a custom alias and a colon `:` to use it with the `root` directive and sub-directive.
Examples:
- `--with` can be used multiple times to add plugins by specifying the Go module name and optionally its version, similar to `go get`. Module name is required, but specific version and/or local replacement are optional.
- `--replace` is like `--with`, but does not add a blank import to the code; it only writes a replace directive to `go.mod`, which is useful when devloping on Caddy's dependencies (ones that are not Caddy modules). Try this if you got an error when using `--with`, like `cannot find module providing package`.
- `--embed` can be used multiple times to embed directories into the built Caddy executable. The directory can be prefixed with a custom alias and a colon `:` to use it with the `root` directive and sub-directive.
#### Examples
```bash
$ xcaddy build \
@ -99,18 +102,22 @@ $ xcaddy build \
--with github.com/caddyserver/ntlm-transport@v0.1.1=../../my-fork
```
You can even replace Caddy core using the `--replace` flag:
You can even replace Caddy core using the `--with` flag:
```
$ xcaddy build \
--replace github.com/caddyserver/caddy/v2=../../my-caddy-fork
--with github.com/caddyserver/caddy/v2=../../my-caddy-fork
$ xcaddy build \
--replace github.com/caddyserver/caddy/v2=github.com/my-user/caddy/v2@some-branch
--with github.com/caddyserver/caddy/v2=github.com/my-user/caddy/v2@some-branch
```
This allows you to hack on Caddy core (and optionally plug in extra modules at the same time!) with relative ease.
---
You may embed directories into the Caddy executable:
```
$ xcaddy build --embed foo:./sites/foo --embed bar:./sites/bar
$ cat Caddyfile
@ -130,6 +137,15 @@ bar.localhost {
```
This allows you to serve 2 sites from 2 different embedded directories, which are referenced by aliases, from a single Caddy executable.
---
If you need to work on Caddy's dependencies, you can use the `--replace` flag to replace it with a local copy of that dependency (or your fork on github etc if you need):
```
$ xcaddy build some-branch-on-caddy \
--replace golang.org/x/net=../net
```
### 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, as if you manually plugged it in and invoked `go run`.