68 lines
2.5 KiB
Markdown
68 lines
2.5 KiB
Markdown
|
||
[](https://goreportcard.com/report/go.i3wm.org/i3)
|
||
[](https://godoc.org/go.i3wm.org/i3)
|
||
|
||
Package i3 provides a convenient interface to the i3 window manager via [its IPC
|
||
interface](https://i3wm.org/docs/ipc.html).
|
||
|
||
See [its documentation](https://godoc.org/go.i3wm.org/i3) for more details.
|
||
|
||
## Start using it
|
||
|
||
In [module mode](https://github.com/golang/go/wiki/Modules), use import path
|
||
`go.i3wm.org/i3/v4`.
|
||
|
||
In non-module mode, use import path `go.i3wm.org/i3`.
|
||
|
||
## Advantages over other i3 IPC packages
|
||
|
||
Here comes a grab bag of features to which we paid attention. At the time of
|
||
writing, most other i3 IPC packages lack at least a good number of these
|
||
features:
|
||
|
||
* Retries are transparently handled: programs using this package will recover
|
||
automatically from in-place i3 restarts. Additionally, programs can be started
|
||
from xsession or user sessions before i3 is even running.
|
||
|
||
* Version checks are transparently handled: if your program uses features which
|
||
are not supported by the running i3 version, helpful error messages will be
|
||
returned at run time.
|
||
|
||
* Comprehensive: the entire documented IPC interface of the latest stable i3
|
||
version is covered by this package. Tagged releases match i3’s major and minor
|
||
version.
|
||
|
||
* Consistent and familiar: once familiar with the i3 IPC protocol’s features,
|
||
you should have no trouble matching the documentation to API and vice-versa.
|
||
|
||
* Good test coverage (hard to display in a badge, as our multi-process setup
|
||
breaks `go test`’s `-coverprofile` flag).
|
||
|
||
* Implemented in pure Go, without resorting to the `unsafe` package.
|
||
|
||
* Works on little and big endian architectures.
|
||
|
||
## Scope
|
||
|
||
i3’s entire documented IPC interface is available in this package.
|
||
|
||
In addition, helper functions which are useful for a broad range of programs
|
||
(and only those!) are provided, e.g. Node’s FindChild and FindFocused.
|
||
|
||
Packages which introduce higher-level abstractions should feel free to use this
|
||
package as a building block.
|
||
|
||
## Assumptions
|
||
|
||
* The `i3(1)` binary must be in `$PATH` so that the IPC socket path can be retrieved.
|
||
* For transparent version checks to work, the running i3 version must be ≥ 4.3 (released 2012-09-19).
|
||
|
||
## Testing
|
||
|
||
Be sure to include the target i3 version (the most recent stable release) in
|
||
`$PATH` and use `go test` as usual:
|
||
|
||
```shell
|
||
PATH=~/i3/build/i3:$PATH go test -v go.i3wm.org/i3
|
||
```
|