dart_dev 2.0.0-alpha

  • Readme
  • Changelog
  • Installing
  • --

Dart Dev Tools #

Pub

Centralized tooling for Dart projects. Consistent interface across projects. Easily configurable.

Motivation #

All Dart (https://dartlang.org) projects eventually share a common set of development requirements:

  • Tests (unit, integration, and functional)
  • Code coverage
  • Consistent code formatting
  • Static analysis to detect issues
  • Documentation generation
  • Examples for manual testing/exploration
  • Applying a LICENSE file to all source files
  • Running dart unit tests on Sauce Labs

Together, the Dart SDK and a couple of packages from the Dart team supply the necessary tooling to support the above requirements. But, the usage is inconsistent, configuration is limited to command-line arguments, and you inevitably end up with a slew of shell scripts in the tool/ directory. While this works, it lacks a consistent usage pattern across multiple projects and requires an unnecessary amount of error-prone work to set up.

This package improves on the above process by providing a number of benefits:

Centralized Tooling #

By housing the APIs and CLIs for these various dev workflows in a single location, you no longer have to worry about keeping scripts in parity across multiple projects. Simply add the dart_dev package as a dependency, and you're ready to go.

Versioned Tooling #

Any breaking changes to the APIs or CLIs within this package will be reflected by an appropriate version bump according to semver. You can safely upgrade your tooling to take advantage of continuous improvements and new features with minimal maintenance.

Consistent Interface #

By providing a single executable (dart_dev) that supports multiple tasks with standardized options, project developers have a consistent interface for development across all projects that utilize this package. Configuration is handled on a per-project basis via a single Dart file, meaning that you don't have to know anything about a project to run tests or static analysis - you just need to know how to use the dart_dev tool.

Note: This is not a replacement for the tooling provided by the Dart SDK and packages like test or dart_style. Rather, dart_dev is a unified interface for interacting with said tooling in a simplified manner.

Tasks #

A task is a single unit of execution within dart_dev. They are identified by a name and may or may not take arguments. Several supported tasks are provided by default. Consumers can supplement the supported tasks with project specific local tasks.

Supported Tasks #

Getting Started #

Install dart_dev

Add the following to your pubspec.yaml:

dev_dependencies:
  coverage: ^0.8.0
  dart_dev: 2.0.0-rc.1
  dart_style: ^0.2.0
  dartdoc: ^0.9.0
  test: ^0.12.0

Create an Alias (optional) #

Add the following to your bash or zsh profile for convenience:

alias ddev='pub run dart_dev'

Configuration #

In order to configure dart_dev for a specific project, you create a dart_dev.yaml file in the root of your project.

analyze:
  libraries:
    - bin/dart_dev.dart
    - lib/executable.dart
    - lib/hooks.dart

apply-license:
  license: LICENSE
  include:
    - bin/
    - lib/
  exclude:
    - lib/src/generated/

coverage:
  report_on:
    - bin/
    - lib/

format:
  include:
    - bin/
    - lib/
  exclude:
    - lib/src/generated/

Help #

The executable has help output for the entire tool as well as each individual task. Run ddev --help or ddev [task] --help to get more information!

Changelog #

1.1.2 #

March 22, 2016

  • Bug fix: The test reporter output now respects the --no-color flag.

  • Bug fix: The test task was previously running the unit test suite even when it was disabled. This has been fixed. Additionally, passing in individual test files/directories overrides the unit and integration suites.

1.1.1 #

February 24, 2016

  • Bug fix: 1.1.0 introduced a regression that caused the test task to no longer default to running the unit test suite and instead run all tests in the test/ directory when the --unit flag was not explicitly set. This has been fixed and should match the behavior from before 1.1.0.

1.1.0 #

February 23, 2016

  • Improvement: Set the coverage task's exit code to non-zero when a test fails.

  • Improvement: Add support for the -n, --name arg for the test task.

  • Bug fix: Catch and silence exception when reading a non-utf8 file during the copy-license task.

  • Bug fix: Make sure the test task observes the --no-unit flag.

1.0.6 #

December 16, 2015

  • Improvement: --strong flag added to the Analyze task.

  • Improvement: The Analyze task's --fatal-hints flag is now implemented by utilizing the --fatal-hints flag on dartanalyzer instead of parsing the output.

  • Documentation: Add zsh completion instructions to the README.

1.0.5 #

November 25, 2015

New Feature: pub server support for tests and coverage #

  • The Test and Coverage tasks now take a --pub-serve flag that will automatically spin up a pub server that is used to run the tests.

  • Tests that require a pub transformer can now be run by passing in this flag!

Changes #

  • Improvement: --fatal-hints flag added to the Analyze task.

1.0.4 #

November 20, 2015

  • Tooling: Bash completions are available in the tool/ directory! See the README for installation instructions.

  • Bug Fix: Dart 1.13 introduced a change to the dart2js output on which the coverage task relied for dart:html detection. This has been fixed.

1.0.3 #

November 12, 2015

  • Improvement: The test task can now run individual test files:

      ddev test test/path/to/test.dart
    
  • Improvement: Widen the dartdoc dependency range.

1.0.2 #

October 15, 2015

  • Improvement: The copy-license task now trims empty leading and trailing lines.

  • Bug Fix: Coverage task no longer incorrectly ignores test files that don't end in _test.dart.

1.0.1 #

September 8, 2015

New Task: docs

  • ddev docs or pub run dart_dev docs

  • Documentation generation via the dartdoc package.

Changes #

  • Improvement: The coverage task now checks for the lcov dependency before trying to generate the HTML report. If missing, installation instructions are given.

  • Improvement: The dependency range for the dart_style package has been widened to >=0.1.8 <0.3.0 to avoid dependency version conflicts.

  • Bug Fix: Fixed a bug that could prevent the HTML coverage report from being opened automatically.

  • Bug Fix: When running the examples task, pub serve errors no longer cause the process to exit prematurely.

1.0.0 #

August 20, 2015

  • Initial version of dart_dev

Use this package as an executable

1. Install it

You can install the package from the command line:


$ pub global activate dart_dev

2. Use it

The package has the following executables:


$ dart_dev

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  dart_dev: ^2.0.0-alpha

2. Install it

You can install packages from the command line:

with pub:


$ pub get

Alternatively, your editor might support pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:dart_dev/executable.dart';
import 'package:dart_dev/hooks.dart';
  
Awaiting analysis to complete.