Nonflavored Prescription Medicine
    Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    lakepublic

    This package has been deprecated

    Author message:

    Deprecated

    WORK IN PROGRESS. THIS DOC IS NOT In SYNC WITH THE ACTUAL CODE (But it illustrates the idea)

    lake

    a very oppinionated make-based build tool for complex and modular web applications that run on NodeJS

    Audience

    Because we build lake especifically for our needs, it turns out to be quite oppinionated about the toolchain. If you are building a complex web application with NodeJS, Couchbase, Component, CoffeeScript, Jade, Eco, Stylus and Mocha, Chai, PhantomJS for testing, you might be interessted in checking out lake as an alternative to grunt, make or cake.

    Installation

    cd my_fancy_node_project
    npm install lake --save-dev
    

    You don't want to install it globally. Instead try this approach and in addition add alias lake="npm-exec lake" to yout .bashrc file. Don't forget to source ~/.bashrc Now you can use lake conveniently from your command line as if it were globally installed.

    Usage

    mkdir -p fancy_project/lib/featureA
    cd fancy_projcet
    lake-init
    cd featureA
    lake-add .
    lake
    # builds featureA
    cd ..
    lake
    # builds all features
    

    Motivation

    We used to build our application with grunt. That didn't scale to well. Grunt has no internal mechanism of finding out whether a certain file needs to be updated; it uncinditionally runs all steps of a task. If a project reaches a certain complexity, this just takes too much time.

    make solved this problem a long time ago. Instead of imperatively defining a set of tasks to be run in sequence, you declare a dependency graph along with a set of actions that create target files from a list of source files. make than figures out what actions need to run in order to create or update the target files. This approach is way more efficient.

    make however has a few issues of its own:

    • Makefiles are hard to read and write
    • it is not trivial to modularize them
    • they tend to get pretty big if you try to make them flexible
    • shell scriptinhg skills are required

    A common pattern to modularize a Makefile is to have a separate Makefile per module and a master Makefile that recusrively uses make to build each module. This paper explains why this pattern is considered harmful and how to correctly modularize the build process by using a single make session and a file per module that is included into a single Makefile.

    Because target names need to be unique within the single Makefile and modules tend to have a common layout, clashing target names are a problem.

    To solve the above problems, we decided to generate our Makefile and the files it includes as part of the build process. This is what lake does prior to spawing a make session.

    Files

    .lake directory

    Stores private data like generated Makefile.mk files etc. Just like the .git direcotey, you normally have no neeed to look into this.

    .lake/features

    Stores a list of locations of Manifest files that contribute targets to the generated Makefile. lake-add adds a location to the list.

    .lake/config

    A JSON file that contains values, that you use in every rule. The key ruleCollection contains an array with paths to your rules, relative to the .lake directory.

    Manifest.coffee

    This file lists various source files that make up different aspects of a particular feature.

    These aspects include:

    • server-side code (coffee)
    • client-side code (coffee)
    • client-side templates (jade)
    • server-side and client-side unit and integration tests (coffee, mocha, chai, phantomjs)
    • CSS styles (stylus)
    • client-side dependencies (components)
    • couchbase view code (js)

    TODO: Manifest format

    local targets

    To solve the clashing target name problem mentioned above, we use a module's directory as a namespace for its targets. In the generated Makefile lake prepends target names with the directory of the module they originate from. That is, it uses the relative path from a Manifest to the .lake directory as a prefix for the targets generated from that Manifest.

    Conversely, lake prefixes the name of a target given on the command line with the current working directory relative to the the location of .lake (i.e. project's root).

    The net effect is that you can build, test and demo the module you are currently working on in isolation.

    Example

    directory structure

    fancy_project
        .lake
            stuff you can ignore
        lib
            featureA
                Manifest.coffee
            featureB
                Manifest.cooffee
    

    shell session

    fancy_project$ lake test
    # Builds and runs unit-tests for the whole project
    
    fancy_project$ cd lib/featureA
    fancy_project/lib/featureA$ lake test
    # Builds and runs unit-tests for feature A only
    

    Name

    We used to call it local-make, then lmake and now it is called lake. It is not related to the LUA build tool.

    Keywords

    none

    install

    npm i lake

    Downloadslast 7 days

    44

    version

    1.0.1

    license

    none

    repository

    github.com

    last publish

    collaborators

    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar