README.md

tpl - minimal project template generator
========================================
tpl is a minimal binary that scaffolds new Rust projects.
Each generated project is a single source file with an ISC
LICENSE, a rustc-based Makefile, a plain-text README and an
mdoc(7) manpage.


Requirements
------------
In order to build tpl you need rustc and libgit2.


Installation
------------
Edit Makefile to match your local setup (tpl is installed into
the /usr/local/bin namespace by default).

Afterwards enter the following command to build and install
tpl:

    make clean install


Running tpl
-----------
Create a new binary project in ./foo/:

    tpl new bin foo

Create a new library project in ./libfoo/:

    tpl new lib foo libfoo

Set the project description (used as the manpage NAME line and
the README title):

    tpl new bin foo -d "say hi to the world"

Vendor dependencies on creation by passing -D once per dep.
A bare name expands to ssh://ijanc@ijanc.org/<name>; a full URL
is used as-is.  Each -D triggers a marmita add inside the new
project, so marmita(1) must be on PATH:

    tpl new lib api -D http -D jackson
    tpl new bin gst -D ssh://ijanc@ijanc.org/marmita

Print the version:

    tpl -V


Generated files
---------------
A binary project contains:

    foo.rs       single-file Rust source with -V flag
    Makefile     rustc build with all/clean/install/ci targets
    README.md    plain-text overview
    foo.1        mdoc(7) manpage in section 1
    LICENSE      ISC license
    .gitignore   ignores build/

A library project contains the same set with foo.3 in place of
foo.1, a Makefile that builds an rlib, exposes test/doc/examples
targets, and a foo.rs that exposes a pub fn version().


Git remotes
-----------
Every generated project is initialized as a git repository via
libgit2 with three default remotes:

    ijanc    ssh://anon@ijanc.org/<name>
    sr       https://git.sr.ht/~ijanc/<name>
    gh       https://github.com/<name>.git


Vendored dependencies
---------------------
The generated bin Makefile auto-discovers vendored deps managed
by marmita(1).  Adding vendor/jackson.rs is enough; the wildcard
rule compiles it into build/libjackson.rlib and passes
--extern jackson=... to the bin link.

If the upstream repo ships a link.mk (e.g. for FFI crates that
need -lgit2), marmita copies it to vendor/jackson.mk and the
generated Makefile -includes it, appending to LINK_FLAGS and
BUILD_ENV automatically.

marmita(1) is available at:

    https://got.ijanc.org/?action=summary&path=marmita.git


Philosophy
----------
Generated scaffolds favour a single source file over a tree of
modules.  No Cargo.toml, no proc-macros, no template engine.
Strings are rendered with std::str::replace.


Download
--------
    got clone ssh://ijanc@ijanc.org/tpl


License
-------
ISC -- see LICENSE.