Make and Bazel

Fairly recently I decided to tinker with Bazel - it had fallen across my radar previously but at the time I dismissed it as something that had enough initial overhead that breaking even didn't seem generally likely. I decided to revisit it after playing with Tilt a bit (which also uses Starlark) given that it has a solid ecosystem, is shinier than make (which I personally don't care about but it can introduce resistance when working with others), and also helps portably address some concerns that otherwise seem to invite messier in-house approaches.

I fairly quickly learned that Bazel is not a great fully general "build" tool - this is no way a knock against it and fits in with the software tools ideology in that it focuses on a certain class of needs without trying to serve too many purposes and be a jack of all trades. Bazel specifically (as fairly clearly stated) is oriented towards producing reproducible artifacts through hermetic environments. This is analogous to pure functions in terms of providing hygienic referential transparency (where referential transparency certainly seems equivalent to reproducible).

Build is in quotes earlier because this is arguably what building is really about, but certain aspects of project management fall outside of that purview - there are often needs to pull information in from the enclosing environment (i.e. for things like release tagging/stamping) and to interact more with some environment in ways that may be less deterministic. There's also the typical build tool concern around prospective cycles when it comes to tools like git which is part of the boundary between that enclosing environment and the project itself.

Going back to the earlier mention of overhead, Bazel can also require a fair amount of work to get configured as desired. So far it has worked fairly flawlessly for me across systems once such configuration is in place, so it certainly feels worth the effort in the long-term, but the return on investment for quick experiments or projects seems more nebulous.

I've therefore gravitated towards a combination of make and Bazel (I also have nix on my queue to pull is an needed but that need has yet to manifest). Both of these are likely to be recurring topics - but given that at the moment there's no content around make I'll quickly say that it is useful as a command orchestrator given it's ubiquity, flexibility, and its core focus of keeping defined directed acyclic graphs up to date. Make therefore is useful to call into Bazel with desired parameters, handle some of the less pure interactions with other systems, and offer a more direct route for experimentation (both in terms of writing rules more quickly and those rules typically being commands that are exposed for tweaking within the shell.

In terms of getting up to speed with Bazel I did read through the fairly older Getting Started With Bazel(1) and Beginning Bazel(2), though the Bazel project itself is well-documented and that seems to be the best resource presently.

Citations

I'm going to be looking to smooth out my handling of citations, starting from inserting the references and working backwards using established patterns. For some context I am currently using Zotero(3) which exports a CSL file using Better BibTeX(4), and I'm planning on using Pandoc to resolve the citations themselves while the pages are converted, so the current goal is to support insertion of citation references within an org file in a way that is convenient and usable by a Pandoc filter (logic I have sitting around would work given a link in the form @key but I would like to have an interface for key selection other than manual lookup and typing.

I'll start with trying out org cite and reading oc.el. I'll first define the bibliography to be the file that is exported to my local "pod" directory that I use for personal information.

(setq org-cite-global-bibliography "~/Documents/pod/bib.yaml")

Based on a quick test of invoking org-cite-insert that value should apparently be some type of list.

(setq org-cite-global-bibliography (list "~/Documents/pod/bib.yaml"))

A basic list results in user-error: No bibliography set

Based on the description of the variable itself, it looks like the files need to be absolute so I'll try that.

(setq org-cite-global-bibliography (list (expand-file-name "~/Documents/pod/bib.yaml")))

Which results in the same error - my thought is that there's a processor or similar missing.

Most of oc.el is unsurprisingly oriented towards exporting and other functionality which I'm not expecting to use. At some point I may want to extract a more focused subset (but the file is also not excessively large so I'm likely to just ignore that). The insertion logic is towards the end of the file where org-cite-insert is the last definition.

The error returned above is nowhere within oc.el - it is likely from the insert processor which I've not yet set. But based on:

org-cite-insert-processor

the initial value is basic which is defined in oc-basic.el. Per the header of that processor, it does not support CSL YAML…for now I may swap Zotero to export JSON.

I removed the previous auto-export and exported to JSON using the keep updated option.

(setq org-cite-global-bibliography (list (expand-file-name "~/Documents/pod/bib.json")))

And now the insert command works! While I may theoretically prefer YAML I can't say it practically makes a difference and JSON parsing is certainly more readily available so I'll probably just leave that as is.

Now I can insert citations, and will just need to pull in and update my Pandoc filter(5) to support working with those references. I'll start to go back and sprinkle in references to citations I have captured (and look at organizing information a bit more).

I should also adopt and configure some slicker completion system for Emacs (helm, ido, whatever else is out there now). I've used some in the past but have tended to stick to stock behavior for the past decade or so but given some of my new approaches and use of Emacs it makes sense to explore pulling in something.

Upon exporting this file I also noticed that the citation I included as a test doesn't render at all…but given that I'd rather switch to Pandoc I'll address that as part of that work.