The HDL Complexity Tool: Installation

The HDL Complexity Tool (HCT) Installation Procedure

Summary

This document describes how to build HCT from source code on Linux, Windows and MacOS systems.

The preferred form of building HCT is to get a release archive and unpack it (which you have presumably done, since you are reading this).

Linux Port

0. Introduction

These instructions will permit you to install the HCT on Linux/Unix systems.

1. Dependencies

To build HCT, your system must support a Unix-like command-line development environment, including the text-processing utilities (sh, grep, awk, sed, etc.) and PERL. On some GNU/Linux systems, this means that you will need to install packages such as `perl' and `make'.

Additionally you will have to install following packages:

GraphViz

Developers will need:

Perl module Parse::Yapp

2. Configuration

Before compiling HCT, you need to "configure" it using the `configure' script provided with the distribution. Configuration serves two distinct purposes: it enables HCT's build system to inspect certain features of your operating system for more robust compilation, and it enables you to choose which features you want the resulting HCT to have.

For example, if you are not root and want to install HCT in subdirectories of your home directory, you can use:

./configure --prefix=$HOME

3. Installation

Use `make' and `make install' to install HCT to directories specified to configure. To install it in a system directory (which is the default), you will need to be root. The standard prefix is "/usr/local/", which can be changed using the `--prefix' configure option.

To delete temporary files created by HCT installation, you can use `make clean'. To delete the files created by HCT installation, you can use `make uninstall' and `make distclean'.

Windows Port

You can configure the Windows port of HCT by running configure.bat (in the main HCT directory). You can run it with no arguments to see the list of possible options. Run it with the option corresponding to the compiler you intend to use to build HCT and follow the (brief) instructions printed on the screen. Currently HCT can be built only with mingw environments.

mingw

Run `configure.bat --mingw' and follow to the printed instructions.

MacOS Port

0. Introduction

These instructions will permit you to install the HCT on MacOS 10.5.8. We expect similar steps can be taken for earlier version of MacOS 10.x.

The installation is a straight forward 4 step process. The steps are to prepare your PERL environment, make the HCT, install the HCT and finally test the HCT.

We are going to use MacPorts (http://www.macports.org/) and CPAN (http://www.cpan.org/) to install the HCT on your Mac.

2. Instructions

STEP 1: Prepare
a. Install MacPorts 1.710 (or latest)
1. http://www.macports.org/install.php
b. Configure MacPorts to have PERL with threading support
1. open a terminal and execute: sudo port
2. issue the port command: deactivate perl5.8
a. If you get an error, please use "installed perl*" to see what you actually have installed
3. issue the port command: activate perl5.8 @5.8.9_3+threads
a. You may have a newer version, so if it gives you a error read it and pick the right +threads
version of PERL to activate. The point is the default is without threading support.
4. You're done! issue the port command: quit
c. Install required CPAN modules
1. Open a terminal and change directory to your HCT installation
2. execute: ./configure
a. The configure script searches your PERL installation to determine if you have the correct
PERL modules to support the HCT
b. Install modules and re-run the configure script
1. execute: cpan -i MODULE_NAME
a. MODULE_NAME is the missing module identified by the configure script
2. execute: ./configure
a. continue to do this until all of the CPAN modules are installed

STEP 2: Make
a. execute: make

STEP 3: Install
a. execute: sudo make install
1. This will install the HCT using your root account

STEP 4: Test
a. execute: hct -h

3. Example

STEP 1: $ ./configure
checking whether make sets $(MAKE)... yes
checking for a BSD-compatible install... /usr/bin/install -c
checking for dot... found
checking for perl5... /opt/local/bin/perl5
checking for perl module GraphViz... ok
checking for perl module Pod::Simple... ok
checking for perl module GD::Graph... ok
checking for perl module Parse::Yapp... ok
checking for perl module Sys::CPU... ok
checking for perl module Time::HiRes... ok
checking for perl module DBI... ok
checking for perl module DBD::SQLite... ok
checking for perl module threads... built with usethreads support
checking for perl module threads... ok
checking for perl module threads version... ok
configure: creating ./config.status
config.status: creating Makefile

STEP2: $ make
make all-host
test ! -f ./lang/configure ; \
echo Configuring in ./lang; \
cd "./lang" || exit 1; \
/bin/sh ./configure \
|| exit 1;
Configuring in ./lang
checking for yapp... found
configure: creating ./config.status
config.status: creating Makefile
echo "#!/bin/sh" > hct ; \
echo `${PWDCMD-pwd}`/hct.pl' $@' >> hct ; \
echo '' >> hct ;

STEP 3: $ sudo make install
cd ./lang || exit 1; \
make install;
Build init.pl...
echo '' > init.pl; \
echo "# WARNING: DO NOT EDIT THIS FILE, USE MAKEFILE INSTEAD." >> init.pl; \
echo "# ANY CHANGE MADE HERE WILL BE LOST!" >> init.pl; \
echo '' >> init.pl; \
for lang in verilog cdl; do \
echo "Register '"$lang"'"; \
make signup-$lang; \
done
Register 'verilog'
test ! -f hdl/verilog.pm ; echo "HDL->load ('"verilog"','"hdl/verilog.pm"','"lang::hdl::verilog"');" >> init.pl;
Register 'cdl'
test ! -f hdl/cdl.pm ; echo "HDL->load ('"cdl"','"hdl/cdl.pm"','"lang::hdl::cdl"');" >> init.pl;
echo '1;' >> init.pl;
/usr/bin/install -c hct /usr/local/bin/hct

STEP 4 $ hct -h
The HDL Complexity Tool
USAGE: [OPTION]... [DIRECTORY/FILE]...

Startup:
-V, --version display the version of HCT and exit.
-?, -h, --help print this help.
--batch=NAME [DIR/FILE] batch.
-T, --use-threads use threads.
--max-threads max threads (if threads defined)
-q, --quiet quiet (no unnecessary output).
-a --list-all do not ignore entries starting with '.'.
-R, --recursive process subdirectories recursively.

Language options:
--force-language=LANG set as default language for input.
--language=LANG after this option can be used options
sensetive to language.

Global output options:
-o, --output-file=FILE output to file.
--output-format=FORMAT output format: terminal, csv. (by default terminal).

Output options sensetive to language:
--output-level=NUMBER output level. (by default 1)
--output-exclude=LIST exclude following list of metrics from report. (separated by commas)
--output-levels print output levels. (only if language set)
--output-metrics print output metrics. (only if language set)
--output-no-modules no modules, only total score.

Debug:
-d, --debug tool debug.
--yydebug=NUM yyparse debug, where num can be:

01 Token reading (useful for Lexer debugging)
02 States information
04 Driver actions (shifts, reduces, accept...)
08 Parse Stack dump
16 Error Recovery tracing
31 Full debugging ouput

Mail bug reports and suggestions to <sladecomputer.org>, <maild2rk.com>.