From f5ae73aba8f98f0212b1928a62ea8fcca3239f7d Mon Sep 17 00:00:00 2001 From: Jon Ruskin Date: Sun, 8 Aug 2021 11:24:13 -0700 Subject: [PATCH] README + linked files cleanup and lint --- README.md | 102 +++++++++--------------------------- docs/adding_a_new_source.md | 19 ++++--- docs/commands/README.md | 8 +++ 3 files changed, 44 insertions(+), 85 deletions(-) diff --git a/README.md b/README.md index 3632f12..13b06da 100644 --- a/README.md +++ b/README.md @@ -37,13 +37,13 @@ See the [v2 migration documentation](./docs/migrations/v2.md) for more info on m Licensed uses the `libgit2` bindings for Ruby provided by `rugged`. `rugged` requires `cmake` and `pkg-config` which you may need to install before you can install Licensed. - > Ubuntu +```bash +# Ubuntu +sudo apt-get install cmake pkg-config - sudo apt-get install cmake pkg-config - - > OS X - - brew install cmake pkg-config +# macOS +brew install cmake pkg-config +``` ### With a Gemfile @@ -56,7 +56,7 @@ gem 'licensed', :group => 'development' And then execute: ```bash -$ bundle +$> bundle ``` ### As an executable @@ -64,25 +64,27 @@ $ bundle Download a package from GitHub and extract the executable. Executable packages are available for each release starting with version 1.2.0. ```bash -$ curl -sSL https://github.com/github/licensed/releases/download//licensed---x64.tar.gz > licensed.tar.gz -$ tar -xzf licensed.tar.gz -$ rm -f licensed.tar.gz -$ ./licensed list +$> curl -sSL https://github.com/github/licensed/releases/download//licensed---x64.tar.gz > licensed.tar.gz +$> tar -xzf licensed.tar.gz +$> rm -f licensed.tar.gz +$> ./licensed list ``` For system wide usage, install licensed to a location on `$PATH`, e.g. `/usr/local/bin`. ## Usage -- `licensed list`: Output enumerated dependencies only. -- `licensed cache`: Cache licenses and metadata. -- `licensed status`: Check status of dependencies' cached licenses. -- `licensed notices`: Write a `NOTICE` file for each application configuration. -- `licensed version`: Show current installed version of Licensed. Aliases: `-v|--version` -- `licensed env`: Output environment information from the licensed configuration. -- `licensed migrate`: Migrate licensed configuration and cached files from a previous major version. +### Available commands -See the [commands documentation](./docs/commands) for additional documentation, or run `licensed -h` to see all of the current available commands. +See the [commands documentation](./docs/commands) for documentation on available commands, or run `licensed -h` to see all of the current available commands. + +### Configuration options + +A configuration file is required for most commands. See the [configuration file documentation](./docs/configuration.md) for more details on the configuration format and available configuration options. + +### Available dependency sources + +Licensed can enumerate dependency for many languages, package managers, and frameworks. See the [sources documentation](./docs/sources) for the list of currently available sources. Sources can be explicitly enabled and disabled as a [configuration option](./docs/configuration/sources.md). ### Automation @@ -96,76 +98,22 @@ The [licensed-ci](https://github.com/marketplace/actions/licensed-ci) GitHub Act The [setup-licensed](https://github.com/marketplace/actions/setup-github-licensed) GitHub Action installs `licensed` to the workflow environment. See the linked actions for usage and details. -### Configuration - -All commands, except `version`, accept a `-c|--config` option to specify a path to a configuration file or directory. - -If a directory is specified, `licensed` will look in that directory for a file named (in order of preference): -1. `.licensed.yml` -2. `.licensed.yaml` -3. `.licensed.json` - -If the option is not specified, the value will be set to the current directory. - -See the [configuration file documentation](./docs/configuration.md) for more details on the configuration format. - -### Sources - -Dependencies will be automatically detected for all of the following sources by default. -1. [Bower](./docs/sources/bower.md) -1. [Bundler](./docs/sources/bundler.md) -1. [Cabal](./docs/sources/cabal.md) -1. [Composer](./docs/sources/composer.md) -1. [Git Submodules (git_submodule)](./docs/sources/git_submodule.md) -1. [Go](./docs/sources/go.md) -1. [Go Dep (dep)](./docs/sources/dep.md) -1. [Gradle](./docs/sources/gradle.md) -1. [Manifest lists (manifests)](./docs/sources/manifests.md) -1. [Mix](./docs/sources/mix.md) -1. [npm](./docs/sources/npm.md) -1. [NuGet](./docs/sources/nuget.md) -1. [Pip](./docs/sources/pip.md) -1. [Pipenv](./docs/sources/pipenv.md) -1. [Swift](./docs/sources/swift.md) -1. [Yarn](./docs/sources/yarn.md) - -You can disable any of them in the configuration file: - -```yml -sources: - bundler: false - npm: false - bower: false - cabal: false -``` - ## Development To get started after checking out the repo, run + 1. `script/bootstrap` to install dependencies 2. `script/setup` to setup test fixtures. - `script/setup -f` will force a clean test fixture environment -3. `script/cibuild` to run the tests. +3. `script/cibuild` to run the tests You can also run `script/console` for an interactive prompt that will allow you to experiment. To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org). -#### Adding sources +### Adding a new source -When adding new dependency sources, ensure that `script/bootstrap` scripting and tests are only run if the required tooling is available on the development machine. - -* See `script/bootstrap` for examples of gating scripting based on whether tooling executables are found. -* Use `Licensed::Shell.tool_available?` when writing test files to gate running a test suite when tooling executables aren't available. -```ruby -if Licensed::Shell.tool_available?('bundle') - describe Licensed::Source::Bundler do - ... - end -end -``` - -See the [documentation on adding new sources](./docs/adding_a_new_source.md) for more information. +See the [documentation on adding new sources](./docs/adding_a_new_source.md) for detailed information on what's required to add a new dependency source enumerator. ## Contributing diff --git a/docs/adding_a_new_source.md b/docs/adding_a_new_source.md index f4c7d2e..dde1dbc 100644 --- a/docs/adding_a_new_source.md +++ b/docs/adding_a_new_source.md @@ -4,13 +4,15 @@ Dependency enumerators inherit and override the [`Licensed::Sources::Source`](../lib/licensed/sources/source.rb) class. -#### Required method overrides +### Required method overrides + 1. `Licensed::Sources::Source#enabled?` - Returns whether dependencies can be enumerated in the current environment. 2. `Licensed::Sources::Source#enumerate_dependencies` - Returns an enumeration of `Licensed::Dependency` objects found which map to the dependencies of the current project. -#### Optional method overrides +### Optional method overrides + 1. `Licensed::Sources::Source.type` - Returns the name of the current dependency enumerator as it is found in a licensed configuration file. @@ -22,12 +24,13 @@ whether `Licensed::Source::Sources#enumerate_dependencies` should be called on t Determining whether dependencies should be enumerated depends on whether all the tools or files needed to find dependencies are present. For example, to enumerate `npm` dependencies the `npm` CLI tool must be found with `Licensed::Shell.tool_available?` and a `package.json` file needs to exist in the licensed app's configured [`source_path`](./configuration.md#configuration-paths). -#### Gating functionality when required tools are not available. +### Gating functionality when required tools are not available. When adding new dependency sources, ensure that `script/bootstrap` scripting and tests are only run if the required tooling is available on the development machine. -* See `script/bootstrap` for examples of gating scripting based on whether tooling executables are found. -* Use `Licensed::Shell.tool_available?` when writing test files to gate running a test suite when tooling executables aren't available. +- See `script/bootstrap` for examples of gating scripting based on whether tooling executables are found. +- Use `Licensed::Shell.tool_available?` when writing test files to gate running a test suite when tooling executables aren't available. + ```ruby if Licensed::Shell.tool_available?('bundle') describe Licensed::Source::Bundler do @@ -47,11 +50,11 @@ Relying on external tools always has a risk that the tool could change. It's ge or other implementation details as these could change over time. CLI tools that provides the necessary information are generally preferred as they will more likely have requirements for backwards compatibility. -#### Creating dependency objects +### Creating dependency objects Creating a new `Licensed::Dependency` object requires name, version, and path arguments. Dependency objects optionally accept a path to use as search root when finding licenses along with any other metadata that is useful to identify the dependency. -##### `Licensed::Dependency` arguments +#### `Licensed::Dependency` arguments 1. name (required) - The name of the dependency. Together with the version, this should uniquely identify the dependency. @@ -71,7 +74,7 @@ Creating a new `Licensed::Dependency` object requires name, version, and path ar 6. errors (optional) - Any errors found when loading dependency information. -##### Creating specialized Dependency objects +#### Creating specialized Dependency objects `Licensed::Dependency` objects inherit from `Licensee::Projects::FsProject` and can override or extend the default `Licensee` behavior to find files for a dependency. diff --git a/docs/commands/README.md b/docs/commands/README.md index dc54cc7..9713ff2 100644 --- a/docs/commands/README.md +++ b/docs/commands/README.md @@ -10,6 +10,14 @@ Run `licensed -h` to see help content for running licensed commands. - [status](status.md) - [version](verison.md) +Most commands accept a `-c`/`--config` option to specify a path to a configuration file or directory. If a directory is specified, `licensed` will look in that directory for a file named (in order of preference): + +1. `.licensed.yml` +2. `.licensed.yaml` +3. `.licensed.json` + +If the option is not specified, the value will be set to the current directory. + ## Adding a new command ### Implement new `Command` class