From 7bfab04765e9e94d517759c9ada16a89a1f25373 Mon Sep 17 00:00:00 2001
From: Bryson Steck <me@brysonsteck.xyz>
Date: Sun, 29 Jun 2025 23:00:37 -0600
Subject: [PATCH] add build, install instructions

---
 README.md | 65 ++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 62 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index c384097..3767b98 100644
--- a/README.md
+++ b/README.md
@@ -11,7 +11,7 @@ A simple watcher program written in Go that runs shell command(s) when the speci
 - Great for students who work on a small set of source files for assignments.
 - Also great for validating configuration files.
 
-## Other Features
+### Other Features
 
 - Choose between listening to kernel events, or wait between checks on an interval.
 - Run the command when any or all files specified are modified.
@@ -22,6 +22,65 @@ A simple watcher program written in Go that runs shell command(s) when the speci
   - Helpful if linters are involved, such as `clang-format`, to avoid multiple runs of a command.
 - Free and Open Source software!
 
+## Installation
+
+You can install this package easily using the Go CLI:
+
+```bash
+# main repo
+go install forge.steck.dev/bryson/listen@latest
+# codeberg mirror
+go install codeberg.org/brysonsteck/listen@latest
+```
+
+## Building
+
+### Using Go
+
+When possible, you should [install Go](https://go.dev/doc/install) on your system and build from source:
+
+```bash
+# you can alternatively clone the codeberg mirror: codeberg.org/brysonsteck/listen
+git clone forge.steck.dev/bryson/listen && cd listen
+go build . -o out/listen
+```
+
+### Using Docker
+
+On **Windows and Linux**, you can alternatively build Listen in a Docker container and copy it out:
+
+```bash
+# you can alternatively clone the codeberg mirror: codeberg.org/brysonsteck/listen
+git clone forge.steck.dev/bryson/listen && cd listen
+
+# replace "linux" with "windows" appropriately
+docker build -t listen-build -f docker/build.linux.Dockerfile .
+mkdir -p out
+docker create --name listen-build-tmp listen-build
+# the exe is located at:
+#   /usr/src/listen/listen - on Linux
+#   C:\build\listen\listen.exe - on Windows
+docker cp listen-build-tmp:/usr/src/listen/listen out/
+docker rm listen-build-tmp
+```
+
+Listen is not intended for use in a standalone Docker environment (currently) due to it's function. However, you could build Listen in a stage and copy the executable to another stage to run a program inside a container:
+
+```dockerfile
+# Example Dockerfile
+FROM golang:1-alpine AS build
+
+WORKDIR /usr/src/listen
+COPY . .
+RUN go build .
+
+FROM python:3 AS main
+
+COPY --from=build /usr/src/listen /usr/local/bin
+# expect a file mounted to /usr/src/main.py to listen to
+CMD ["listen", "-f", "/usr/src/main.py", "--", "python", "main.py"]
+```
+
 ## History
 
 Listen was originally a Perl script that came about when I wanted something for my college assignments and also needed to learn Perl for an internship. I wrote it once and haven't touched it or improved upon it since I created it.
@@ -42,9 +101,9 @@ the Free Software Foundation, either version 3 of the License, or
 
 This program is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 GNU General Public License for more details.
 
 You should have received a copy of the GNU General Public License
-along with this program.  If not, see <https://www.gnu.org/licenses/>.
+along with this program. If not, see <https://www.gnu.org/licenses/>.
 ```