cloud8421 / elm.mk Goto Github PK

View Code? Open in Web Editor NEW

19.0 5.0 3.0 94 KB

Makefile based toolchain for Elm projects. Inspired by Erlang.mk

Makefile 66.09% Ruby 33.91%

elm devd wellington makefile boilerplate javascript

elm.mk's Introduction

Elm.mk

A fast, close-to-zero dependencies toolchain for Elm-based single page applications.

Philosophy

The main goal of this boilerplate is to minimise the needs for external dependencies while providing an effective development environment. This means that it tries as much as possible to bundle pre-compiled utilities to accomplish the needed tasks.

Features

Cross-platform (OS X + Linux 64bit - help with Windows would be nice)
Elm StartApp installation
Project scaffold generation
Elm compilation with warnings
Scss compilation via Wellington
Watch and recompile via modd
Live reload via devd
File generators based on templates
Optional support for elm test

Setup from scratch

mkdir my_new_project && cd my_new_project
curl -o elm.mk https://raw.githubusercontent.com/cloud8421/elm.mk/master/elm.mk
make -f elm.mk

This will generate the needed folder structure and files. Note that at the end of make -f elm.mk, you're left with an empty Makefile that includes elm.mk, so that you can extend it for your needs and/or override its behaviour.

Project workflow

Main commands:

make: compiles the project into build (installing dependencies if needed)
make dist: compiles the project into dist with production optimisations
make serve: serves the build folder with a local http server
make watch: starts the file watcher and the http server, recompiling files on save
make help: shows all main tasks
make config: shows paths used for project files
make tests: runs the entire test suite
make tests-watch: starts the test watcher, which reruns tests when files change

Some guidelines:

Files generated into build should not be edited manually.
Files generated into dist should not be edited manually. In addition, they're passed through optimisation steps which make them very difficult to read.
All other files can be modified.
Source .elm files should be placed in src.
Use boot.js to start your Elm application and define all ports-related glue code with the external world. The file gets copied automatically to build.
scss/main.scss is the stylesheet main file.
index.html gets copied the way it is into build.

It may also be worth checking out the documentation for the software used in this boilerplate (like Devd or Modd), as they provide functionality that it's not covered here.

Elm.mk development

If you're interested in contributing, please make sure you keep tests up to date.

After cloning this repository, just run make test (requires Ruby 2.x in your path, no extra dependencies).

Tests are maintained in tests.rb.

FAQs/Comments

Looking for a different version

Try the legacy branch.

I don't think this should use X, Y is a better fit.

As long as it's easy to install in portable format (i.e. download in the project folder and run), please feel free to state the case for a replacement

Why is feature X missing?

Probably because I haven't thought about it.

Why Make?

Make is ubiquitous, mostly pre-installed (or very easy to install) and language-agnostic. It takes some time to adjust to it, but it's fast, effective and modular.

This make task is not optimal, it's much better if you change it like this!

Please submit a PR, I'm happy to learn

I don't know Make, but I'd like to help. Where can I learn more?

elm.mk's People

Contributors

Stargazers

Watchers

Forkers

sjfloat c11z mburri

elm.mk's Issues

Update elm-test when 0.17 compatible version is available

The current version only works on 0.16

Support images

Add a basic task that copies images to the build folder, possibly doing some basic optimisation.

Separate generated elm files

After using this a few times, I always find myself separating the generated Main.elm file into Main.elm, View.elm, State.elm and Types.elm. Should just generate separate files from the start.

Won't compile if all .elm files are in main src/ dir

Heya, saw this on elm-discuss. I think this project is a great idea! I replaced my simple Makefile with yours, and tried it out. First issue I ran into was that it requires you two have at least one directory of .elm files inside your /src dir. The project I tried it out in is very simple, and all .elm files are directly in the "root" /src dir. Here's some output demonstrating the issue:

$ make
test -s src/Main.elm || echo "$main_elm" > src/Main.elm
make: *** No rule to make target 'src/**/*.elm', needed by 'build/main.js'.  Stop.
$ mkdir src/asdf
$ touch src/asdf/asdf.elm
$ make
test -s src/Main.elm || echo "$main_elm" > src/Main.elm
elm make src/Main.elm --yes --warn --output build/main.js
Success! Compiled 1 modules.                                        
Successfully generated build/main.js
...

This would be a PR, but I don't really know make well enough!

Investigate installing Elm if not present

Elm is currently available either as a standalone download or as a npm package. It would be interesting to see if it's possible/feasible/reasonable to integrate this with elm.mk.

include elm-format as dev tool

It would be nice to include elm-format in the dev-tools - even if it's not used to build the project I usually set up my editor to use elm-format on save but i don't want to install it globally.

It would also help beginners to setup their dev environment

Update for Elm 0.17

This includes:

Check if current compile flags are still valid
Update src/Main.elm template
Update interop.js template
Check make test to confirm it still works as expected

Create Vagrant Box for testing

Testing would be easier with a Vagrant box, ideally a very lightweight linux distribution like Alpine.

Tests not passing

after PR #25 tests do not pass with output

elm.mk$ make
...
./tests.sh
test #15 "ls dummy/build/images/test.jpg" failed:
	program terminated with code 2 instead of 0
test #16 "ls dummy/build/images/test.png" failed:
	program terminated with code 2 instead of 0
2 of 20 examples tests failed in 0.017s.
Makefile:4: recipe for target 'test' failed
make: *** [test] Error 1

It looks like build and build/images are part of the INSTALL_TARGETS. Calling make after make install results in the images being cp'd to build/images/images which breaks the test. The dist is unaffected because it is not part of the INSTALL_TARGETS and images are cp'd directly from the root images folder.

Removing build and build/images from the INSTALL_TARGETS solves the problem.

I am opening a PR, and would love your feedback. Great project by the way.

Revise interop layer

Currently there's some confusion on the interop layer side of things, particularly around file naming.

The current interop boilerplate is used to boot the app and handle all interop-related code, but this is not clear.

A good change would be to rename interop to app: that way elm.mk generates 2 files:

a main.js file, from Elm compilation, which is the compiled Elm Main module.
a app.js file, which boots the Elm app and handles ports.

This way we can also revise the target resolution logic, so that if a file is called app.js is considered a pure js file, while anything else would be considered an Elm target.

Replace goat

Goat doesn't show proper output for failed tasks, making it difficult to debug compilation errors.

Other alternatives, like https://facebook.github.io/watchman/, do a better job, but they're tricky to include as they need to be compiled.

Support prod target

For production it would be interesting to generate different artifacts:

Use https://developers.google.com/closure/compiler/ on generated elm files and interop files
Compress CSS
Compress HTML (not sure about this)