{"id":19031482,"url":"https://github.com/plandes/clj-mkproj","last_synced_at":"2026-05-12T12:41:10.178Z","repository":{"id":80107490,"uuid":"73450498","full_name":"plandes/clj-mkproj","owner":"plandes","description":"Generates boilerplate projects","archived":false,"fork":false,"pushed_at":"2018-09-26T17:04:24.000Z","size":111,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-02T04:14:38.602Z","etag":null,"topics":["boilerplate","clojure","command-line-tool","template","yaml"],"latest_commit_sha":null,"homepage":null,"language":"Clojure","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/plandes.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-11-11T06:03:57.000Z","updated_at":"2018-09-26T17:04:25.000Z","dependencies_parsed_at":null,"dependency_job_id":"f0285830-afb3-4d8a-8b3b-89b08ecedf6c","html_url":"https://github.com/plandes/clj-mkproj","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plandes%2Fclj-mkproj","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plandes%2Fclj-mkproj/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plandes%2Fclj-mkproj/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plandes%2Fclj-mkproj/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/plandes","download_url":"https://codeload.github.com/plandes/clj-mkproj/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240080773,"owners_count":19744925,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["boilerplate","clojure","command-line-tool","template","yaml"],"created_at":"2024-11-08T21:23:46.877Z","updated_at":"2026-05-03T07:30:19.187Z","avatar_url":"https://github.com/plandes.png","language":"Clojure","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Easy to Use Project Scaffolding/Templating Tool\n\n[![Travis CI Build Status][travis-badge]][travis-link]\n\n  [travis-link]: https://travis-ci.org/plandes/clj-mkproj\n  [travis-badge]: https://travis-ci.org/plandes/clj-mkproj.svg?branch=master\n\nThis application generates boilerplate projects by interpolating variables in\nfiles recursively starting at a top level directory recursively.  The\napplication is written in Clojure, runs on the Java Virtual Machine and\nuses [Velocity](https://velocity.apache.org) for all file parameter\nsubstitution in templated file.\n\nFeatures include:\n* [Interpolate](https://en.wikipedia.org/wiki/String_interpolation) strings in templated files.\n* Each parameter supports example, description and default metadata.\n* Support for parameter substitution for directory names.\n* Map file and directory names templating parameter variables to different\n  paths in the same or other directory in the target (see\n  the [dsl](#directory-level-dsl) section).\n* Date support using [DateTool](https://velocity.apache.org/tools/devel/apidocs/org/apache/velocity/tools/generic/DateTool.html).\n\nThis is meant to supplement your own custom projects much like:\n* `mvn archetype:generate`\n* `lein new default`\n* `sbt new`\n\nSee the\n[https://github.com/plandes/template](https://github.com/plandes/template/tree/master/lein) project\nfor a complete `mkproj` template.\n\n\u003c!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc --\u003e\n## Table of Contents\n\n- [Obtaining](#obtaining)\n- [Usage](#usage)\n    - [Quick Start](#quick-start)\n    - [Command line help](#command-line-help)\n    - [Project Metadata](#project-metadata)\n        - [Configuring the Project](#configuring-the-project)\n- [Project Metadata DSL](#project-metadata-dsl)\n    - [Top Level DSL](#top-level-dsl)\n    - [Directory Level DSL](#directory-level-dsl)\n- [Building](#building)\n- [Documentation](#documentation)\n- [Changelog](#changelog)\n- [License](#license)\n\n\u003c!-- markdown-toc end --\u003e\n\n\n\n## Obtaining\n\nThe latest release binaries are\navailable [here](https://github.com/plandes/clj-mkproj/releases/latest).\n\n\n## Usage\n\nThe application is a command line program that includes an *action* parameter\nto tell it what to do followed by parameters specific to that action.  The end\nresult is a project you can literally build out of the box.\n\n\n### Quick Start\n\nAll usage commands below use\nthe [example](https://github.com/plandes/template/tree/master/lein) project\ntemplate.  For them to work, first clone the project:\n```bash\n$ mkdir ../template \u0026\u0026 wget -O - https://api.github.com/repos/plandes/template/tarball | tar zxfv - -C ../template --strip-components 1\n```\n\nCreate a configuration file:\n```bash\n$ mkproj config -s ../template/lein\nmkproj: wrote configuration file: mkproj.yml\n```\n\nLearn what parameters need to be set and what they mean:\n```bash\n$ mkproj describe\n```\nSee [project metadata](#project-metadata) section for more innformation.\n\nNow edit the `mkproj.yml` based on what we learned in the *describe*\nstep.  See [configuring the project](#configuring-the-project) for more\ninformation.\n\nFinally build out the project from the template:\n```bash\n$ mkproj make\nmkproj: reading config file: mkproj.yml\nmkproj: making project from ../template/lein\nmkproj: creating new project ../template/lein -\u003e clj-someproject\n...\n```\n\n### Command line help\n\nGet the command line usage by supplying no arguments:\n```sql\n$ mkproj\nusage: mkroj \u003cdescribe|config|make\u003e [options]\n  describe    list all project info and configuration parameters as markdown\n  -s, --source \u003cfile\u003e                  the source directory containing the make-proj.yml file\n  -l, --level \u003clog level\u003e  INFO        Log level to set in the Log4J2 system.\n  -c, --config \u003cfile\u003e      mkproj.yml  location of the project instance configuration file\n\n  config      create a project configuration file (use -c with make command)\n  -s, --source \u003cfile\u003e                   the source directory containing the make-proj.yml file\n  -l, --level \u003clog level\u003e   INFO        Log level to set in the Log4J2 system.\n  -d, --destination \u003cfile\u003e  mkproj.yml  the output file\n\n  make        generate a template rollout of a project\n  -s, --source \u003cfile\u003e                  the source directory containing the make-proj.yml file\n  -l, --level \u003clog level\u003e  INFO        Log level to set in the Log4J2 system.\n  -c, --config \u003cfile\u003e      mkproj.yml  location of the project instance configuration file\n  -p, --param \u003cparams\u003e                 list of project parameters (see describe command)\n```\n\n\n### Project Metadata\n\nThere are two main YAML files:\n* **make-proj.yml** is the top level project template metadata file (see\n  the [lein example](https://github.com/plandes/template/blob/master/lein/make-proj.yml)\n* **mkproj.yml** is the *project instance* configuration file that's generated\n  from the `make-proj.yml` file\n\nTo get information and parameters we can set in the *project instance*\n`mkproj.yml` file, which are used to interpolate in the destination target\nfile:\n```bash\n$ lein run describe -s ../template/lein\nZensol Clojure Project\n----------------------\nSimple Clojure project designed to work with [Zensol Build](https://github.com/plandes/clj-zenbuild).\n\n## Parameters\n  * sub-group: maven group coordinate (eg com.zensols.nlp), default: \u003ccom.zensols\u003e\n  * group: maven artifact coordinate (eg parse)\n  * package: root package space (creates \u003cpackage\u003e.core) (eg zensols.nlp), default: \u003czensols\u003e\n  * project: github repo name (eg clj-nl-parse), default: \u003cclj-\u003e\n  * user: github user name (eg plandes)\n  * app-name: script name used with appassembler (eg nlparser)\n  * project-name: null (eg Natural Language Parse), default: \u003cWRITE ME\u003e\n  * project-description: a short project descsripion (eg This library provides generalized library to deal with natural language.), default: \u003cWRITE ME\u003e\n```\n\n\n#### Configuring the Project\n\nAfter creating the configuraiton data in the [*config*](#usage) step modify\neach property if necessary (in most cases you'll want to).  Note taht the\ndescription data is added for convenience during editing, but it isn't used in\nthe project file creation.\n```yaml\ndescription: project configuration generated 2017-01-31 06:05:15\nsource: /Users/landes/view/template/lein\ntemplate-directory: make-proj\ncontext:\n- property:\n    description: 'github repo name (ex: clj-nl-parse)'\n    name: project\n    value: clj-\n- property:\n    description: 'very short few word project description (ex: clj-nl-parse)'\n    name: project-name\n    value: WRITE ME\n...\n```\n\n**Imporant:** Every `mkproj.yml` should have a `project` property since\nthis is the name of the top root level subdirectory to create.  For this\nreason, the `make-proj.yml` that the `mkproj.yml` is generated from\n*should* have a `:project` section in the `:context` as well.\n\n\n## Project Metadata DSL\n\nEach template has a project metadata [YAML](http://yaml.org) configuration file\nthat includes what each parameter to be interpolated/substituted in the\nresulting output.  The output of this data is\nthe [project metadata](#project-metadata) `mkproj.yml` file.\n\nThere are two configuration `.yml` files:\n* [top level](#top-level-dsl)\n* [directory level](#directory-level-dsl)\n\n\n### Top Level DSL\n\nHere's a\n[portion](https://github.com/plandes/template/blob/master/lein/make-proj.yml)\nfrom the [lein](https://github.com/plandes/template/tree/master/lein) template\nto illustrate part by part:\n```yaml\nproject:\n  name: Zensol Clojure Project\n  description: Simple Clojure project designed to work with [Zensol Build](https://github.com/plandes/clj-zenbuild).\n```\nThis defines top level project information\n\n```yaml\n  template-directory:\n    description: root of source code tree to interpolate\n    example: view/template/proj\n    default: make-proj\n```\nThis provides (`default parameter`) the path to the directory that has the files that will be\nrecursively processed and interpolated.\n\n```yaml\n  generate:\n    excludes:\n      - makefile$\n      - LICENSE$\n```\nThe generation section tells what and how to generate the files.  The\n`excludes:` provides a list of regular expressions that indicate which files\nto leave as is *without* interpolation.\n\n```yaml\n  context:\n    sub-group:\n      description: maven group coordinate\n      example: com.zensols.nlp\n      default: com.zensols\n```\nThe `context:` section provides a name, description and an optional default and\nexample of what the parameter values are.  When processing files the example is\nused if default isn't given.\n\n\n### Directory Level DSL\n\nEach directory (including the root) can have a `dir-config.yml` that defines\nmappings for directories and files.   Let's start with a file mapping example\nthat comes from the [Emacs Lisp](https://github.com/plandes/template/blob/master/elisp/make-proj/dir-config.yml) template:\n```yaml\npackage:\n  generate:\n    - file-map:\n        source: source-file.el\n        destination: ${project-name}.el\n```\nThe `file-map` parameter repeats with two children nodes: `source` and\n`destination`.  In this case we map `source-file.el` in the source template\ndirectory to the name of the package with the `.el` extension mapped to the\ntarget output directory.\n\nOur next example comes from the [lein](https://github.com/plandes/template/blob/master/lein/make-proj/src/clojure/dir-config.yml) template:\n```yaml\n#set($package-dir = $package.replace(\".\", \"/\").replace(\"-\", \"_\"))\n#set($dst-ver-dir = $group.replace(\"-\", \"_\"))\npackage:\n  generate:\n    - directory-map:\n        source: pkg-dir\n        destination: ${package-dir}\n    - directory-map:\n        source: ver-dir\n        destination: ${dst-ver-dir}\n```\nThe first two lines that start with `#`\ntell [Velocity](https://velocity.apache.org) to set two variables `package-dir`\nand `dst-ver-dir`, which are used in the template.\n\nLike `file-map` the `directory-map` is a list with a source and destination\n(target) that map a directory.\n\nThe target directory can be any *N* deep subdirectory and the tool creates\nthese directories for those that don't exist.  This is the case with the\n`package-dir` variable as we replace a Clojure (as the case with Java) a\ndirectory structure that's isomorphic with the package namespace.  The second\nreplace from dashes to underscores is a Clojure package to directory specific\nnamespace syntax rule.\n\n\n## Building\n\nTo build from source, do the folling:\n\n- Install [Leiningen](http://leiningen.org) (this is just a script)\n- Install [GNU make](https://www.gnu.org/software/make/)\n- Install [Git](https://git-scm.com)\n- Download the source: `git clone https://github.com/clj-mkproj \u0026\u0026 cd clj-mkproj`\n- Download the make include files:\n```bash\nmkdir ../zenbuild \u0026\u0026 wget -O - https://api.github.com/repos/plandes/zenbuild/tarball | tar zxfv - -C ../zenbuild --strip-components 1\n```\n- Build the distribution binaries: `make dist`\n\nNote that you can also build a single jar file with all the dependencies with: `make uber`\n\n\n## Documentation\n\nAPI [documentation](https://plandes.github.io/clj-mkproj/codox/index.html).\n\n\n## Changelog\n\nAn extensive changelog is available [here](CHANGELOG.md).\n\n\n## License\n\nCopyright (c) 2016, 2017, 2018 Paul Landes\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of\nthis software and associated documentation files (the \"Software\"), to deal in\nthe Software without restriction, including without limitation the rights to\nuse, copy, modify, merge, publish, distribute, sublicense, and/or sell copies\nof the Software, and to permit persons to whom the Software is furnished to do\nso, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplandes%2Fclj-mkproj","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fplandes%2Fclj-mkproj","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplandes%2Fclj-mkproj/lists"}