Git Product home page Git Product logo

shoe's Introduction

Shoe

CircleCI

Clojure make - a simple Clojure build tool, based on tools-deps (deps.edn).

Rationale

When building software, you shouldn't have to think about your build tool differently than how you think about your application. All you need to do is write some functions that perform your build steps. And there is no reason to couple these functions to a build framework (ร  la Leiningen & Boot).

Clojure has always had the ability to execute Clojure code from the command line via clojure.main. The reason this approach never took off (until now) was because you needed to determine the classpath to start the JVM. This required that you pull in some sort of Maven dependency resolver (i.e. Pomegranate) or, more likely, fall back to the existing tools that solve this problem - Leiningen or Boot. To address this missing piece, the Clojure team has released tools-deps. Tools-deps has a narrow, well-defined goal -- classpath creation.

The Clojure CLI combines clojure.main functionality with tools-deps classpath creation, making running Clojure programs easy. It still felt like there was a missing piece, however. I'd like to be able to run arbitrary Clojure functions from the command line, not just a -main. You can absolutely do this with the Clojure CLI, however it requires a few extra options and writing some code in the command line. Further, I'd like my functions to parse command line arguments without needing to write the boilerplate code that tools.cli requires. It'd also be great if I could build up a library of common functions that I can use across all my projects. And as soon as you have a set of general, reusable functions, you want a way to pass default, project-specific options to these functions. Thus the creation of shoe (name inspired by Rake).

At its core, shoe is simply a collection of functions that can be easily run using the Clojure CLI. shoe provides an optional CLI to make running functions easier.

Clojure CLI Usage

All the built in functions are located in the tasks directory and contained within their own folder. For example, the repl task source code is located at tasks/repl. The code is structured in this way to make running from the Clojure CLI easy. This is best shown by example. Let's launch a REPL using the repl task.

Starting a REPL with Clojure CLI

$ clojure -Sdeps '{:deps {shoe-tasks.repl {:git/url "https://github.com/ComputeSoftware/shoe" :sha "873e1a2e50a9dd961a0a251a12aed9e13b538416" :deps/root "tasks/repl"}}}' -m shoe-tasks.repl
nREPL server started on port 45023

That's a bit nasty to type everytime you want to start a REPL. Let's make this easier with an alias! Create a deps.edn file in your current directory (or edit your user deps.edn file located at ~/.clojure/deps.edn) and add the below alias:

{:aliases {:repl {:extra-deps {shoe-tasks.repl {:git/url   "https://github.com/ComputeSoftware/shoe"
                                                 :sha       "873e1a2e50a9dd961a0a251a12aed9e13b538416"
                                                 :deps/root "tasks/repl"}}
                  :main-opts  ["-m" "shoe-tasks.repl"]}}}

This makes starting a REPL short and sweet.

$ clojure -A:repl
nREPL server started on port 34093

The same technique can be used for all of the tasks in the tasks directory. Note that :deps/root will need to be changed to the correct relative Git directory when working with other tasks. For example, the test task would have :deps/root set to tasks/test.

You can see all of the options that a task supports by using the --help flag.

$ clojure -A:repl --help
...

At this point the aformentioned problem should be clear -- we need a way to minimize the amount of configuration and to set default options for tasks within the scope of a project. This is where the shoe CLI comes in.

Shoe CLI Usage

The shoe CLI is written in ClojureScript and available as a NPM module.

Installation & Upgrading

To install or upgrade shoe, run this command.

npm install -g shoe-cli

Starting a REPL with shoe

Remember all the configuration we needed to do to start a REPL via the Clojure CLI? shoe does all the automatically, exposing the function call as a command line task.

$ shoe repl
nREPL server started on port 36389

In the background shoe is parsing the command line arguments passed to it, resolving the string "repl" to an actual function call, and passing parsed command line options to that resolved function (it executes the function with clojure in a sub-process, isolating dependencies on the task level). For those curious, dive deeper in the implementation details section.

As you saw with the launching a REPL using the Clojure CLI, you're also able to print a help menu for tasks via the shoe CLI.

$ shoe repl --help

All tasks, built-in and user defined, always have a help menu.

Basic Usage

shoe repl # Launch a nREPL

shoe uberjar # package the project and dependencies as standalone jar

shoe test # run all tests in the project

Custom tasks

TODO: write this

Configuration

shoe's configuration is stored in shoe.edn which is loaded from the directory where you launched shoe.

Implementation Details

TODO: write this

TODO

  • Write moar specs
  • CLI opts Spec support
  • Tasks need to be able to register a cleanup function called on exit. Task functions should probably have a way of communicating data to the cleanup function.
  • Ability to list all tasks registered
  • Validate config with Spec
  • when dynamic deps are added to tools-deps we can have task level dependencies
  • use color in console printing

Tasks

  • build a thin jar
  • install a jar into local m2
  • push to a remote repo
  • watch filesystem
  • show out of date deps
  • create new project
  • lein javac

shoe's People

Contributors

compute-ci avatar kennyjwilli avatar

Stargazers

 avatar

Watchers

 avatar  avatar  avatar

shoe's Issues

Better task options with task composition

All shoe tasks are just Clojure functions that take a map of options. This makes calling tasks from the command line, REPL, and other tasks really easy. Default options are provided to tasks from the shoe.edn file under the :task-opts key. Because the uberjar task uses the aot task, a user may specify task options for the aot task under :task-opts and expect those options to be used in uberjar task. Right now, those options for aot are not used because the uberjar task is simply a function that reads its task options from the uberjar entry in :task-opts.

jar task

Need a task that is the equivalent of lein jar.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.