Skip to content

Latest commit

 

History

History
68 lines (41 loc) · 4.28 KB

ARCHITECTURE.md

File metadata and controls

68 lines (41 loc) · 4.28 KB
Raw

appmap-ruby architecture

Official documentation

The official documentation for appmap-ruby is at appland.com/docs.

Integration with appmap-js

Most of the analytics functionality for AppMap JSON is implemented in appmap-js. In particular, packages/cli. appmap-ruby includes the source code and dependencies of @appland/appmap. Check the Rakefile for references to npm and/or yarn to see how the packaging works.

appmap-ruby executes command-line programs provided by @appland/appmap; it doesn't attempt to load a Node.js library in-process. @appland/appmap commands are designed to produce clean output on stdout, which is obtained and processed by appmap-ruby.

Swagger (OpenAPI) generation

appmap-ruby provides a Rake task to generate Swagger files from AppMaps. The majority of the Swagger is generated by calling out to appmap-js swagger. appmap-ruby makes it Ruby-friendly by wrapping it with Rake, and by adding doc strings to the Swagger by converting RDoc to HTML. It also post-processes the Swagger to remove volatile parameter examples, producing openapi_stable.yml.

Configuration

The Swagger task supports configuration settings via appmap.yml. Put the settings under the swagger key.

The API version can also be specified explicitly in Ruby code, when the Rake task is defined:

AppMap.configuration.swagger_config.project_version = \
  [ 
    'v',
    File.read(File.join(Rails.root, 'VERSION')).strip,
    '_',
    `git rev-parse --short HEAD`.strip
  ].join

Note From experience, it seems like almost all of the value of the Swagger gen is provided by openapi_stable. Therefore, in the future this may become the only output from the Rake task, and the RDoc to HTML functionality may be removed.

The package appmap/swagger is loaded automatically by appmap, when Rake is available in the bundle.

Blogs and videos

Depends (incremental testing)

appmap-ruby provides a Rake task to automatically run tests and update AppMaps as local source files and test files are modified. It leans heavily on the depends command provided by @appland/appmap. To understand how the Rake tasks work, consider running appmap-js depends on your local AppMaps - you can touch source files to see the dependency detection in action.

However, computing which AppMaps need updating as a result of source files changes is only part of the story. depends also has to:

  • Detect added, changed, and removed test files.
  • Run the tests which are determined to be out of date.
  • Update the AppMap index after updating the AppMaps.
  • Remove any AppMaps which refer to tests that have been deleted.

Because depends has some complexity, there is an API module that implements key commands. To understand depends in further detail, after trying out the @appland/appmap command, read this API.

The package appmap/depends is loaded automatically by appmap, when Rake is available in the bundle.

Configuration

The Depends task supports configuration settings via appmap.yml. Put the settings under the depends key. Some configuration settings for Depends are specified as fully-qualified method names (e.g. Class::Name.method_name). The Rake task definition code should ensure that the code for any customized methods is loaded and available. At the time of this writing, the primary reasons for overridding the default Depends behavior are:

  • Inject custom environment variables into the test command.
  • Override the default test command string.

There are separate settings for rspec and minitest.

Blogs and videos