pub package

This package provides a set of Grinder tasks that make it easy to release a Dart and Flutter packages.

Build Status github last commit github build github issues

Table of contents

Getting started


In able to use the GitHub publishing features of this package your development setup must meet the following requirements:

  • git must be available in your command path (most people reading this will have this requirement met, if not see - Installing Git)
  • you have a GitHub account and have setup a personal access token (see the documentation - Creating a personal access token)
  • A fine grain token requires the following permissions:
    • Read and write - Administration - for the Homebrew tap repository creation
    • Read and write - Contents - to update repository content and crete the release for the tap
    • Read-only - Metadata - mandatory for all fine-grained personal access tokens

Make sure that you .gitignore your publish_tools.yaml file to prevent publishing your token to GitHub

pubspec.yaml setup

In your pubspec.yaml the following to the dev_dependencies section:

  grinder: ^0.9.2
  publish_tools: ^0.1.0+11

Optionally, provide a non-default path for your configuration .yaml file: (remember to .gitignore it)

publish_tools: tool/config.yaml

publish_tools.yaml setup

Create a folder named tool (which will already exist if you use the grinder package). In this folder create you publish_tools configuration file.

## this is a minimal config, several fields will be assigned default values

## If the github key is present, it will override the default (grab values from .git folder)
# github:
#   repoUser: [your github user]
#   repoName: [defaults to 'name' from pubspec.yaml]

## If the templates key is present, defaults are overridden.  Below matches the default config.
# templates:
#   - name:
#     type: overwrite
#   - name:
#     type: prepend

commit: 'sample commit message'


import 'package:grinder/grinder.dart';
import 'package:publish_tools/publish_tools.dart';

main(args) async {


@DefaultTask('Just keeping it real')
build() {
} templates

publish_tools can make it easier for you to keep your and file up to date. To do this it uses mustache templates to dynamically re-create your README and CHANGELOG when you run the appropriate grinder task. To configure your project to make use of this functionality, you need to have a and mustache template available to the build tool.

The quickest and simplest way to get your templates in place is to copy your existing and into the tool folder. Now you can update these files with dynamic fields that will be replaced when the pt-markdown grinder task is run.

For instance, in this README file in the pubspec.yaml setup section above, there are instructions and an example of how to update your pubspec.yaml to use this tool. The publish_tools version in the README is set dynamically with a variable. Here is the section of markup for the same section in the tool/ mustache template:

  grinder: ^0.9.2
  publish_tools: ^{{ pubspec.version }}

The value for {{ pubspec.version }} is filled in automatically by the pt-markdown grinder task.

Or for the the following template might be used:

# Changelog

## {{ pubspec.version }}

{{ changes }}

By default the file is overwritten each time the pt-markdown task runs. However thee file is prepended by default. This means that the supplied template will be added to the start of the existing file.

Other available values that can be used dynamically are:

object attribute description
pubspec Information contained within the project pubspec.yaml file.
name Project name.
version Project version.
homepage URL pointing to the package’s homepage (or source code repository).
documentation URL pointing to documentation for the package.
description Project short description.
publishTo Specifies where to publish a package.
github Values from the publish_tools config file related to GitHub.
repoUser The GitHub username associated with this project.
repoName The GitHub repository name for this project.
homebrew Values from the publish_tools config file related to HomeBrew.
className The name of the class created for the HomeBrew ruby file for the tap repository that will be created and published to GutHub
description The description given in the ruby tap repository
homePage The description given in the ruby tap repository. By default this is the same as pubspec.homepage.
binSrc The file name of the source code for the command line binary of the project. The file is expected to be found in the homebrew.binFolder and by default the expected file name is [].dart.
executableName The name of the compiled executable for the command line binary to be used by end-users, defaults to
binFolder The folder that contains the binary source for the command line executeable, defaults to bin
meta_path The location to write the meta.dart file that is used to supply pubspec info to the cli binary executable, defaults to lib/meta.dart.
commit The commit message supplied in the publish_tools config file.
changes The changes (for the supplied in the publish_tools config file.

Grinder Tasks

Here is the list of grinder tasks available in this package:

Task name Description
pt-analyze Analyze Dart code in a directory - dart analyze .
pt-format Idiomatically format Dart source code - dart format .
pt-doc Generate API documentation for Dart projects - dart doc .
pt-test Generate API documentation for Dart projects - dart test .
pt-meta Creates a file meta.dart in the folder specified by the config (defaults to src/util/), this file contains a JSON representation of the pubspec.yaml file, giving access to that information to cli programs.
pt-markdown Processes any markdown templates references in the config. Usually the and the, the templates can use mustache syntax to access data from the ptConfig object.
pt-commit Commit the project to github `git add .`, `git commit {{ ptConfig.commit }}`, `git pull --tags`, `git tag v${pubSpec.version}`, `git push --tags`, `git push`. Only if {{ pubSpec.version }} has changed, will a new tag be created.
pt-release Create a Release for the current project in GitHub
pt-homebrew Create a HomeBrew tap for the command line executable for this project
pt-clean Remove build and homebrew repository folders created by this tool.
pt-publish Publish the current package to

In the next major release

  • Chocolatey support
  • NPM support


publish_tools is a library of additional grinder tasks that ease publishing a Dart or Flutter package to