ArchRuby User Manual (also available in portuguese)

1. Installation and Requirements
2. Definition of Modules
3. Architectural Rules
4. Violations Reports
5. Architectural Visualization
6. Applying the Tool

Installation and Requirements

The ArchRuby Tool is available as a GEM for the Ruby language. Therefore, follows the same pattern of an Ruby Gem instalation. Just execute the command gem install archruby and the installation will be done automatically.

ArchRuby has dependecies of the followings Gem's:
* ruby_graphviz
* ruby_parser
* sexp_processor

All dependecies will be installed along with installation of the GEM archruby. The library Graphviz must be installed in your system.

Definition of Modules

The module definition in ArchRuby is made through YAML file. It's through the modules that the system mapping is done.

Example:

            <module_id >:
              (files | gems): ’< pattern_desc > {, < pattern_desc >}’
              [(allowed | forbidden): ’< module_id> {, < module_id>}’]
              [(required): ’< module_id > {, < module_id>}’]
              

Where < module_id > is the name of the module. Modules can be composed by files (files) or Gems (gems) that must be defined by at least one < pattern_desc > delimited by commas. The pattern matching is based on shell glob (default Rubyfile library) to map multiple files at once. To detect divergences—dependencies, that exist in the source code but are not prescribed by the planned architecture, for each module we define the ones that it is allowed to depend (allowed) or not (forbidden), which are defined by at least one, delimited by commas. Likewise, to detect absences—dependencies, that do not exist in the source code but are required by the planned architecture, for each module we definethe ones that it must depend (required), which are defined as aforementioned. It is worth noting that a definition for a particular module can combine required with allowed or forbidden. However, it cannot have allowed and forbidden in a same module definition.

Architectural Rules

Inside of a module definition, it's possible to define the architectural rules that will be apply in the module. It's through these architectural rules that the tool will detect if the planned architecture it is being followed.

There are three types of architecture rules that can be used in ArchRuby:
* Allowed
* Forbidden
* Required

The allowed type indicates that the module are authorized to access the modules that are in the allowed key as explained at section Definition of Modules. As well as the forbidden type that indicates the module can't access the modules that are in the forbidden key. Finally, the required type indicates which modules are required to depend.

Example:

            controller:
              files: 'app/controllers/**/*.rb'
              allowed: 'model, integracao_twitter, integracao_pdf, actioncontroller, view'
            

The above example shows the architectural rule of controller module. The module is composed by all files .rb which are in the folder app/controllers and it's allowed to access the modules: model, integracao_twiter, integracao_pdf, actionctroller and view.

Violations Reports

The conformance process outputs a file reporting the detected architectural violations (divergences and absences).

Example of divergence:

              1 divergence:
              2  class_origin: TwitterController
              3  line_origin: 21
              4  class_target: Twitter::REST::Client
              5  module_origin: controller
              6  module_target: twitter
              7  message: module controller is not allowed to depend on module twitter
              

Example of absences:

              1 absence:
              2  class_origin: TesteClass
              3  line_origin:
              4  class_target:
              5  module_origin: model
              6  module_target: activerecord
              7  message: not implement a required module
              

The report indicate the type of violation (line 1), informations from the origin class (lines 2-4) and from the target class, and the violated rule (line 7).

Architectural Visualization

Upon the conformance process, our approach provides a high-level view of the concrete architecture. The model is a directed dependency graph whose vertices represent the modules defined in the architectural rules specification and edges represent dependencies established between the modules, which are differentiated when refer to architectural violations.

Example of image generated by ArchRuby:

Applying the Tool

For use the ArchRuby just execute the command:

                archruby --arch_def_file=< path definição da arquitetura > --app_root_path=< path root do sistema >
              

Remember that this command only will be available after the installation of ArchRuby.