generator-lxgo

Yeoman generator for vendoring Go applications outside of GOPATH with a grunt build system. Build and vendoring based on https://getgb.io. Including build, run, test, release with update changelog, packaging and coverage.

Requires

• golang environment with GOPATH - http://golang.org/doc/install
• nodeJs | io.js - https://nodejs.org/download

Getting Started

What is Yeoman?

Not every new computer comes with a Yeoman pre-installed. He lives in the npm package repository. You only have to ask for him once, then he packs up and moves into your hard drive. Make sure you clean up, he likes new and shiny things.

Install dependencies

NodeJs global modules yeoman, grunt-cli and generator-lxgo:

$ npm install -g yo grunt-cli generator-lxgo

The following dependencies are automatically installed when you create the project.

• github.com/constabulary/gb/...
• github.com/axw/gocov/gocov
• gopkg.in/matm/v1/gocov-html
• github.com/AlekSi/gocov-xml

Create and run your application

Initiate the generator and Yeoman and create your application, run:

$ mkdir your_project_name
$ cd your_project_name
$ yo lxgo

Get vendor packages and run the dummy app with default task

$ grunt

Generated project

The Project created is ready to run. This is achieved by dummy data, they are located in src. You can start with programming by replacing the dummy data.

Get and install application

In your project directory: (example: $Home/Projects)

Install the build helper module and make a first build to run.

$ cd app_name
$ npm install
$ grunt

Grunt starts the default task, get vendor dependencies and go run app_name. The dummy data test application starts. You can check if everything has been installed correctly and work properly with it. Also check the other tasks which will be described below.

Configuration in package.json

The important part is as follows:

  "name": "app_name",
  "version": "0.0.0",
  "coverPackages": [
    "lib",
    "build-test-1"
  ],...

name

The name of the project. Will provide some as a default value for the builds used.

version

Is automatically increased with grunt release. Used for the packaging.

coverPackages

This list should include all packages of the project that is required for coverage. There are only checked packages in the list of coverage.

Go project directory structure

The go project runs outside from GOPATH. Important is the correct directory structure. Grunt adds a GOPATH environment for each task. The environment contains the root of the project and the root of the directory _vendor. (GOPATH=./:_vendor)

.
├── CHANGELOG.md
├── Gruntfile.js
├── README.md
├── _dist
│   ├── test-1
│   └── test-1.0.0.1.darwin-x64.tar.gz
├── _reports
├── bin
│   └── test-1
├── etc
├── package.json
├── pkg
├── src
│   └── test-1
│       ├── cmd
│       │   └── test-1
│       │       ├── main.go
│       │       └── main_test.go
│       ├── test-1.go
│       └── test-1_test.go
├── test-1.sublime-project
├── test-1.sublime-workspace
├── tmp
│   └── cover_package.out
└── vendor

• _dist: The distrubution folder. Is generated by grunt grunt build or release.
• _reports: Here are the reports generated by grunt cover.
• bin: The binaries generated by grunt run or grunt build or gb build. (Goes well with: gb build && bin/binary-name or grunt build && bin/binary-name)
• etc: Miscellaneous and scripts for installation.
• src: Your source code. Remember to organize everything in packages.

Not like this:

.
├── src
    ├── main.go
    ├── second-app.go
    └── helper.go

better this way:

.
├── src
    └── test-1
        ├── cmd
        │   ├── test-1
        │   │   ├── main.go
        │   │   └── main_test.go
        │   └── second-app
        │       ├── main.go
        │       └── main_test.go
        ├── test-1.go
        └── test-1_test.go

Organize all executable under cmd.

Including gb for build and versioning

Many grunt tasks internally use gb. An example:

$ grunt run

Is a simplification of:

$ gb build
$ bin/binary-name

You can always use gb for your tasks. For help use this:

$ gb help

An example of tests:

// Test all packages
$ gb test

# The result:
$ PASS
$ PASS

That's ok if it has to happen quickly. For more information you can use "grunt test".

# Test all packages with grunt test
$ grunt test

# The result
$ ok  	test-1	0.007s	coverage: 100.0% of statements
$ ok  	test-1/cmd/test-1	0.009s	coverage: 100.0% of statements

More information about "grunt test" you find in the section grunt.

Package management with gb vendor

For package management use "gb vendor". Help to use "gb vendor" with:

$ gb help vendor

Usage:

    gb vendor command [arguments]

The commands are:

    fetch       fetch a remote dependency
    update      update a local dependency
    list        lists dependencies, one per line
    delete      deletes a local dependency
    purge       purges all unreferenced dependencies
    restore     restore dependencies from the manifest

Use "gb vendor help [command]" for more information about a command.

Additional help topics:

Use "gb vendor help [topic]" for more information about that topic.

An example of the typical use of "gb vendor":

# Get the mgo package
$ gb vendor fetch gopkg.in/mgo.v2

Save the package in vendor/src directory and save the package information in the manifest file.

	"dependencies": [
		{
			"importpath": "gopkg.in/mgo.v2",
			"repository": "https://gopkg.in/mgo.v2",
			"revision": "22287bab4379e1fbf6002fb4eb769888f3fb224c",
			"branch": "v2"
		},
		{
			"importpath": "gopkg.in/tomb.v2",
			"repository": "https://gopkg.in/tomb.v2",
			"revision": "14b3d72120e8d10ea6e6b7f87f7175734b1faab8",
			"branch": "v2"
		}
	]

Now all dependencies can be restored any time with a particular version.

# Restore packages with version
$ gb vendor restore

Be careful with an update. The revision will be overwritten during an update with the latest. Recommendation, save all previous revisions.

# Backup the actual manifest
$ cp vendor/manifest manifest.backup

# Make your updates
$ gb vendor update --all

# Check if everything works

# If not works, restore the manifest.backup.
$ mv manifest.backup vendor/manifest

# If works, delete the manifest.backup.
$ rm -f manifest.backup

This variant is also the task of "grunt manifest:backup" and "grunt manifest:restore" More information about gb

Let's start with Grunt tasks

grunt

Default task, starts gb restore to load the vendors and grunt run to perform run binary.

# Default task
$ grunt

grunt go[:"arguments"]

A mapper for go command. Executes the arguments that were passed in the string.

• Sets the GOPATH to $ ProjectPath:$ProjectPath/vendor
• Runs the command "go arguments"

Examples:

# List packages
$ grunt go:"list ./src/..."

# Test all packages with coverage
$ grunt go:"test ./src/... -cover"

# Build a package
$ grunt go:"build -v -o app-test ./src/test-1/cmd/test-1"

grunt format

Format and test the code with commands "go fmt .src/..." and "go vet ./src/..." # Format the code $ grunt format

grunt run[:binary-name]

Builds packages and starts the specified Binary. If no Binary is specified by default started the default binary with the app-name.

# Start the default binary with the app-name
$ grunt run

# Start a named Binary.
$ grunt run:binary-name

grunt test[:"arguments"]

A mapper for go test. Executes the arguments that were passed in the string. Testing all packages with coverage is default.

# Default test all packages with coverage
$ grunt test

# Test all packages without coverage as argument string
$ grunt test:"./src/..."

# Test only package with coverage
grunt test:"package-name -cover"

grunt cover[:packagename][:report]

Prints an extensive test coverage report to the console, in html or in XML that is important for CI systems. This task only uses the packages that are specified in the package.json.coverPackages.

# Coverage all packages and view result on console
$ grunt cover

# Coverage package-name and view result on console
$ grunt cover:package-name

# Coverage all packages and view result in html report
# The HTML report opens after creating the browser.
$ grunt cover:html

# Coverage package-name and view result in html report
# The HTML report opens after creating in the browser.
$ grunt cover:package-name:html

# Coverage all packages and save result in XML report
$ grunt cover:xml

# Coverage package-name and save result in XML report
$ grunt cover:package-name:xml

grunt manifest:backup|restore

Restore all packages with version from the manifest in directory vendor, or exactly just load one package. If only one package is loaded, the package information is saved in the manifest file. This is important for an update with gb vendor. See [Package management with gb vendor](Package management with gb vendor)

# Backup the vendor/manifest
$ grunt manifest:backup

# Restore the manifest.backup
$ grunt manifest:restore

grunt build[:"flags"]

Builds with gb build the distribution in _dist directory. Add the arguments as build flags that were passed in the string.

# Build the distribution in ./_dist/app-name
$ grunt build

  # Run the distribution
$ _dist/app-name/bin/binary-name

  # Show help for the build flags
$ gb help build

# Build the distribution in ./_dist/app-name with flags
$ grunt build:"-v -f"

This task "grunt build" summarizes several steps together. The following example shows all the manual steps for this task.

# Format the code (go fmt ./src/...)
$ grunt format

# Empty the bin directory
$ grunt clean:bin

  # Build with flags
$ gb build -v

# Clean the _dist directory
$ grunt clean:dist

# Copy the distribution files
$ grunt copy:dist

grunt package

Creates a compressed archive from the dist directory for publication. This task is automatically used by the following release task. Therefore it is never actually used directly or needed. In Mac and Linux a tar.gz is generated. In Windows, a zip is generated.

# Build a compressed archive from _dist directory
# The name of archive is: app-name.version.GOARCH.{tar.gz|zip}
$ grunt package

grunt release[:version-type]

Generates a complete release of the application. The following steps are performed:

• gb vendor restore (restore all vendor packages from manifest file)
• grunt test (test all packages)
• grunt build (build distribution)
• Increases the version number in the Package.json
• Update the CHANELOG with commit messages
• Git commit and tag with versions number
• grunt package (created a compressed archive)

The commit messages are created according to a scheme of Google Angular. Thus, the CHANGELOG is generated automatically using the commit messages. Commit Message Format: https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#commit-message-format

# Build an revision release (version 0.0.x)
$ grunt release

# Build an minor release (version 0.x.0)
$ grunt release:minor

# Build an mayor release (version x.0.0)
$ grunt release:major

Contributing

In lieu of a formal styleguide take care to maintain the existing coding style. Lint and test your code using grunt.

Get Generator from Github

$ git clone [email protected]:private/generator-lxgo.git
$ cd generator-lxgo
$ npm install

Feel free to make a contribution or to improve the generator.

• Write your functionality.
• Write a unit test for your functionality.
• Test your changes
• Document your functionality
• Make a pull request

Important Note

If the unit tests are insufficient for you and you want to test the generator completely but have it already installed, you first have to remove the previously installed generator lxgo.

$ npm uninstall -g generator-lxgo

Then you can work with the current generator-lxgo that you want to test.

$ cd /path/to/generator-lxgo
$ npm link

You can unlink it again after testing with:

$ npm uninstall -g generator-lxgo

And replace it with the actual generator:

$ npm install -g generator-lxgo

Development

The generator is currently under development. Please refer to the changelog and roadmap for further information on development progress.

Author

Litixsoft GmbH

License

Copyright (C) 2015 Litixsoft GmbH [email protected] Licensed under the MIT license.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.