Skip to content

Commit

Permalink
update readme
Browse files Browse the repository at this point in the history
Adds install instructions for using modules, as well as adding the
new google group link.  Fixes magefile#200.
  • Loading branch information
natefinch committed Nov 30, 2018
1 parent 11d1591 commit f89c4cb
Showing 1 changed file with 30 additions and 20 deletions.
50 changes: 30 additions & 20 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,29 +5,36 @@

## About

Mage is a make/rake-like build tool using Go. You write plain-old go functions,
Mage is a make-like build tool using Go. You write plain-old go functions,
and Mage automatically uses them as Makefile-like runnable targets.

## Installation

Mage has no dependencies outside the Go standard library, and builds with Go 1.7
and above (possibly even lower versions, but they're not regularly tested).

Install mage by running
**Using GOPATH**

```
go get -u -d github.com/magefile/mage
cd $GOPATH/src/github.com/magefile/mage
go run bootstrap.go
```

This will download the code into your GOPATH, and then run the bootstrap script
to build mage with version infomation embedded in it. A normal `go get`
(without -d) will build the binary correctly, but no version info will be
embedded. If you've done this, no worries, just go to
$GOPATH/src/github.com/magefile/mage and run `mage install` or `go run
bootstrap.go` and a new binary will be created with the correct version
information.
**Using Go Modules**

```
git clone https://github.com:magefile/mage
cd mage
go run bootstrap.go
```

This will download the code and then run the bootstrap script to build mage with
version infomation embedded in it. A normal `go get` (without -d) or `go
install` will build the binary correctly, but no version info will be embedded.
If you've done this, no worries, just go to `$GOPATH/src/github.com/magefile/mage`
and run `mage install` or `go run bootstrap.go` and a new binary will be created
with the correct version information.

The mage binary will be created in your $GOPATH/bin directory.

Expand All @@ -40,7 +47,9 @@ You may also install a binary release from our

## Discussion

Join the `#mage` channel on [gophers slack](https://gophers.slack.com/messages/general/) for discussion of usage, development, etc.
Join the `#mage` channel on [gophers slack](https://gophers.slack.com/messages/general/)
or post on the [magefile google group](https://groups.google.com/forum/#!forum/magefile)
for discussion of usage, development, etc.

# Documentation

Expand All @@ -50,15 +59,16 @@ see [godoc.org/github.com/magefile/mage/mage](https://godoc.org/github.com/magef

# Why?

Makefiles are hard to read and hard to write. Mostly because makefiles are essentially fancy bash scripts with significant white space and additional make-related syntax.

Mage lets you have multiple magefiles, name your magefiles whatever you
want, and they're easy to customize for multiple operating systems. Mage has no
dependencies (aside from go) and runs just fine on all major operating systems, whereas make generally uses bash which is not well supported on Windows.
Go is superior to bash for any non-trivial task involving branching, looping, anything that's not just straight line execution of commands. And if your project is written in Go, why introduce another
language as idiosyncratic as bash? Why not use the language your contributors
are already comfortable with?
Makefiles are hard to read and hard to write. Mostly because makefiles are
essentially fancy bash scripts with significant white space and additional
make-related syntax.

# TODO
Mage lets you have multiple magefiles, name your magefiles whatever you want,
and they're easy to customize for multiple operating systems. Mage has no
dependencies (aside from go) and runs just fine on all major operating systems,
whereas make generally uses bash which is not well supported on Windows. Go is
superior to bash for any non-trivial task involving branching, looping, anything
that's not just straight line execution of commands. And if your project is
written in Go, why introduce another language as idiosyncratic as bash? Why not
use the language your contributors are already comfortable with?

* File conversion tasks

0 comments on commit f89c4cb

Please sign in to comment.