i-published-a-rust-crate.md

beep bap babadoop

i needed a file locking implementation for another project i'm working on, and none of the ones i found on crates.io seemed to satisfy everything i wanted:

simple api (basically just "try to get an exclusive lock on a whole file"): many crates provide features like async compatibility, locking byte ranges, etc. that i just didn't need
non-blocking: a few crates were based on stuff like O_EXCL on POSIX or specifying a restrictive share mode on Windows, which has the problem that the only way to try to get the lock is to commit to a potentially blocking operation
guaranteed cleanup on crash: this is another problem with using exclusive open modes as a locking mechanism (the file can be left behind on a crash, leaving no way to know if the lock is held or not)
portable: a few crates only work on one platform family, typically POSIX
uses standard bindings to the native locking api instead of rolling custom ones
based on flock() on POSIX systems, not fcntl(): conventional wisdom actually says to prefer fcntl() locks because they're more stable across network shares, but for the use case i'm interested in (only allowing 1 process access to a particular directory), flock() is better-behaved because it applies to a single file descriptor rather than every file descriptor in the process

so, i made this crate! it's about as simple as i could make it while fulfilling everything i wanted.

i've never released a rust crate (or really any publically-available package) before, so it was a bit of an interesting experience. here's the highlights:

i found one neat tool that helped with the process a little bit, cargo msrv, which helps you find the minimum supported rust version for your crate
i was surprised that you need a github account to publish a crate, despite the fact that you don't need to host your crate's source on github; they seem to use it just as an authentication provider. which i honestly don't really have a problem with, but it's a little odd
there's a handy checklist of all the things you need to check before you publish a crate, which i found very helpful; i wouldn't have remembered to add crate-level documentation or to write my code examples with ? instead of unwrap(), for example
i got around 150 downloads in the first couple days that the crate's been up, but i'm preeeeetty sure that those are mostly indexing/mirroring/etc. bots that just happen to download the crate to do their job, not to actually use it. so i have no idea how many real users i have 🙃

i hope at least a few other folks find it useful! c:

beep bap [babadoop](https://crates.io/crates/file_locking)

i needed a file locking implementation for another project i'm working on, and
none of the ones i found on crates.io seemed to satisfy everything i wanted:

- simple api (basically just "try to get an exclusive lock on a whole file"):
	many crates provide features like `async` compatibility, locking byte ranges,
	etc. that i just didn't need
- non-blocking: a few crates were based on stuff like `O_EXCL` on POSIX or
	specifying a restrictive share mode on Windows, which has the problem that
	the only way to try to get the lock is to commit to a potentially blocking
	operation
- guaranteed cleanup on crash: this is another problem with using exclusive
	open modes as a locking mechanism (the file can be left behind on a crash,
	leaving no way to know if the lock is held or not)
- portable: a few crates only work on one platform family, typically POSIX
- uses standard bindings to the native locking api instead of rolling custom
	ones
- based on `flock()` on POSIX systems, not `fcntl()`: conventional wisdom
	actually says to prefer `fcntl()` locks because they're more stable across
	network shares, but for the use case i'm interested in (only allowing 1
	process access to a particular directory), `flock()` is better-behaved
	because it applies to a single file descriptor rather than every file
	descriptor in the process

so, i made this crate! it's about as simple as i could make it while fulfilling
everything i wanted.

i've never released a rust crate (or really any publically-available package)
before, so it was a bit of an interesting experience. here's the highlights:

- i found one neat tool that helped with the process a little bit, [`cargo
	msrv`](https://crates.io/crates/cargo-msrv), which helps you find the
	**m**inimum **s**upported **r**ust **v**ersion for your crate
- i was surprised that you need a github account to publish a crate, despite
	the fact that you don't need to host your crate's source on github; they seem
	to use it just as an authentication provider. which i honestly don't really
	have a problem with, but it's a little odd
- there's a handy
	[checklist](https://rust-lang.github.io/api-guidelines/checklist.html) of all
	the things you need to check before you publish a crate, which i found very
	helpful; i wouldn't have remembered to add crate-level documentation or to
	write my code examples with `?` instead of `unwrap()`, for example
- i got around 150 downloads in the first couple days that the crate's been up,
	but i'm preeeeetty sure that those are mostly indexing/mirroring/etc. bots
	that just happen to download the crate to do their job, not to actually use
	it. so i have no idea how many real users i have 🙃

i hope at least a few other folks find it useful! c: