mkly/README.org

* mkly
A Guile build script for Lilypond (and other) projects

** Features
1. Provides a default set of rules, so you don't have to.
2. Provides a full-blown programming language for writing rules.
3. Tiny; trivial to hack on.
4. Implemented and configured using the only reasonable language (a Lisp 😏)

** Non-goals
1. Incremental builds

** Installation
Guile must be available at =/usr/bin/guile=
1. Place =mkly= in your $PATH or your project root
2. Make it executable -
   : chmod u+x mkly
3. Place =mkly-rules.scm= in your project root.
4. In your project root, run -
   : ./mkly

** The defaults
The default rules make certain assumptions about your project structure -
1. You have a main.ly in the project root containing all musical parts
2. Individual parts are contained in part-*.ly files
3. Emitted PDF/MIDI/PNG files go into a directory called "output" (or "output-<current branch>" if you use a VCS)

Of course, you can change the rules to suit whatever project structure you want.

Some default variables are defined -
1. project-name - by default, the basename of the parent directory
2. shell-path - path to the shell you want to use for running your commands

** Defining rules
Rules are returned as a list by the procedure =rules=, defined in the project-specific =mkly-rules.scm=.

** Built-in helper functions
1. =(use-dir! DIR)= - creates DIR if it does not exist. DIR must be a string. Raises an error if DIR exists and is not a directory. Returns DIR.
2. =(vcs-current-branch)=
3. =(parent PATH)= - returns the parent directory component of PATH, or #f if none is present.
4. =(getcwd-base)= - returns the basename of the current directory.

** TODO
*** Certain [50%]
1. [X] Make it declarative - define options and their effect, and the structure of the command, separately from the code that makes it happen.
2. [X] Use regexps to define target names and how the output file name(s) derive from them.
3. [X] Name files differently if PAC is on - The upside of this is, you don't accidentally send someone the point-and-click-enabled version of the file.
   The downside is, it's easy to have file-pacON.pdf open during editing, while the script is actually compiling to file.pdf (or vice-versa) [fn:1], and wonder why your score isn't updating.
4. [X] Create output directory if it doesn't exist!
5. [X] Remove duplicate layer of CLI options - currently there's a needless extra layer of CLI options for options which already exist. Should make code simpler, UI familiar.
   + But the Lilypond CLI is ugly - what's better, "pac=off", or "-dno-point-and-click"? :\
     - After the revamp, the script doesn't (yet) aim to want to support options like this; the idea is that the user specifies a /situation/ as a target, and all options relevant to that situation are passed (as specified in the rules by the user). It's a "maybe" to-do.
6. [ ] Tab completion of specified target names
7. [ ] Multiple targets in one command e.g. to compile both the main score and the parts in one command.
8. [ ] Targets containing other targets.
   + I've tried calling the script itself with the required targets - not sure if that actually works. Especially considering that #7 - multiple targets in one command - isn't implemented yet.
   + If mkly is not in the user's $PATH and is invoked as =./mkly=, the shell won't be able to find it if it calls itself. We can construct the path to the script (using getcwd)
9. [-] Shell globs, both in targets and in actions.
   * [X] Document shell-path as a user variable
   * [ ] Use shell-path to run commands
10. [-] Sub-project operations
    1. [X] Specify targets for sub*-project(s), instead of project in current working directory.
    2. [ ] Use sub-project-specific mkly-rules.scm if present, else use project-root mkly-rules.scm
    3. [ ] I want to compile a particular target in every subproject. (use globs)

    (Old) implementation notes
    1. Maybe...if the input file in a target entry is just a "/" (or maybe "->"?), the target name will be understood as being the target to run in either
       1. all subdirectories directly below the directory containing the current build.scm (in this case, it is an error if any of these subdirectories do not contain a build.scm)
       2. all subdirectories in which a build.scm can be found, directly below the directory containg the current build.scm
11. [ ] Expand branch detection to include more VCSs.

[fn:1] These are likely to happen if you have a compile-with-last-command-on-save setup, like in my Emacs.

*** Maybe [0%]
1. [ ] Allow users to define (command-line) options and their effect.
2. [ ] VCS branch integration - check what branch you're on. If it's branch X (e.g. "main"), do nothing. If it's something else, add the name to the output file.
   + Or to the output directory name, e.g. files from the main branch go to "output/", files from branch "foo" go to "output-foo/", etc.
3. [ ] Default rules for orchestral projects - for target part-<instrument>.ly, compile <instrument class>/<instrument>.ly
4. [ ] Make =rules= into a macro
5. [ ] Implement Scheme expressions as an action.
   * one possible way - all actions are Scheme expressions - for shell commands, create a ($ ...) form (with =$= doing what =run= does now) which is =eval=-uated if it matches a target.

*** Bugs
1. Barfs when placed in and run from directories with a path containing non-ASCII characters.

   This is a [[http://lists.gnu.org/archive/html/guile-user/2015-12/msg00054.html][Guile]] [[https://debbugs.gnu.org/cgi/bugreport.cgi?bug%3D22229][bug]].