Installing Components¶

Use the install subcommand to add a component to your current working copy. The URL path to the component and the version are required to install a new component. This can be found using a repository browser or the svn ls subcommand.

Example: Installing a Component¶

After viewing the component repository, we decide to pull in version 3.0.0 of the rook component.

$ hcm install rook --version 3.0.0
INFO:Installing component rook version 3.0.0
INFO:Validating all files for component rook are committed.
INFO:Removing local component directory
INFO:Installation complete

HCM will use the paths in the HCM_URL_PATHS environment variable. It will search each path for a matching component name and version.

Example: Installing the latest version of a component¶

If the version argument is not use, then HCM will install the latest version of the component.

$ hcm install rook
INFO:Installing component rook
INFO:Validating all files for component rook are committed.
INFO:Removing local component directory
INFO:Installation complete

Example: installing component when files under the component directory are not committed¶

HCM validates every file under the local component directory is checked in. If this is not the case, then HCM will not install over the existing directory.

$ ../../bin/hcm install rook --version 3.0.0
INFO:Installing component rook version 3.0.0
INFO:Validating all files for component rook are committed.
ERROR:The following files must be committed or removed:
M       rook/rtl/rook.vhd

This behavior can be overridden by using the –force command line option.

$ hcm install rook --version 3.0.0 --force
INFO:Installing component rook version 3.0.0
INFO:Removing local component directory
INFO:Installation complete

Example: installing from an external repo¶

When installing from an external repo, HCM must use the svn export command.

$ hcm install pawn --version 1.0.0 --url http://svn/external_repo/blocks
INFO:Installing component pawn version 1.0.0
INFO:Validating all files for component pawn are committed.
INFO:Removing local component directory
INFO:Installation complete

Performing an svn status command shows a new directory has been created.

$ svn status
?       pawn

The directory must be added using the svn add command…

$ svn add pawn
A         pawn
A         pawn/hcm.json
A         pawn/rtl
A         pawn/rtl/pawn.vhd

… and then committed.

$ svn commit pawn

Note

The last two steps are left to the user to perform.

Example: Installing using an external¶

HCM can install components using externals. An external is a essentially a pointer to directory in a repository.

$ hcm install pawn --version 3.0.0 --external
INFO:Installing component pawn version 3.0.0
INFO:Validating all files for component pawn are committed.
INFO:Removing local component directory
INFO:Updating externals
INFO:Installation complete

Checking the svn status of the current directory…

$ svn status
 M      .
X       castle
X       pawn

…shows the properties of the existing directory have been modified and pawn is an external. The directory must be committed to keep the change to 3.0.0 of pawn.

Example: Installing Component and It’s Dependents¶

HCM can keep track of dependencies between components using dependency file. This file is generated by the user and committed with the component before it is published. If HCM detects this file, it install any of the components listed.

$ hcm install rook --dependencies
INFO:Installing component rook
INFO:Removing local component directory
INFO:Installing dependencies
INFO:Checking for dependencies of rook
INFO:Installing component king
INFO:Removing local component directory
INFO:Checking for dependencies of king
INFO:Installing component castle
INFO:Removing local component directory
INFO:Checking for dependencies of castle
INFO:  No Dependencies found
INFO:Installing component pawn
INFO:Removing local component directory
INFO:Checking for dependencies of pawn
INFO:  No Dependencies found
INFO:Installing component queen
INFO:Removing local component directory
INFO:Checking for dependencies of queen
INFO:Installation complete

In this example the dependencies.yaml file for rook contained the following:

---
requires:
  queen:
  king:

and the queen component contained a dependencies.yaml file:

---
requires:
  rook:
  king:
  pawn:

and the king component contained a dependencies.yaml file:

---
requires:
  pawn:
  castle:

HCM will break an circular dependencies and only install a component once.

Example: Installing Component and Install the Latest Version of Dependents¶

If a component has already been installed, HCM will not install over it. This behavior can be modified by using the –upgrade command line argument. HCM will install the latest version of every dependent component if this argument is used.

$ hcm install rook --dependencies --upgrade
INFO:Installing component rook
INFO:Removing local component directory
INFO:Installing dependencies
INFO:Checking for dependencies of rook
INFO:Installing component king
INFO:Removing local component directory
INFO:Checking for dependencies of king
INFO:Installing component castle
INFO:Removing local component directory
INFO:Checking for dependencies of castle
INFO:  No Dependencies found
INFO:Installing component pawn
INFO:Removing local component directory
INFO:Checking for dependencies of pawn
INFO:  No Dependencies found
INFO:Installing component queen
INFO:Removing local component directory
INFO:Checking for dependencies of queen
INFO:Installation complete