NAME

Dir::Project - Project Environment determination

SYNOPSIS

  # Perl
  use Dir::Project;
  Dir::Project::get_set_all();
  # Makefiles
  include $(DIRPROJECT_PREFIX)/lib/project_dir.mk
  # Example script dispatching
  cd ~/project1
  project_dir --project
     /path/to/project1
  my_tool my_args....   # Executes project1/.../my_tool
  cd ~/project2
  project_dir --project
     /path/to/project2
  my_tool my_args....   # Executes project2/.../my_tool

DESCRIPTION

Dir::Project provides a way to locate a source-controlled directory (CVS, Subversion, Perforce, Git, etc) using only the current working directory (cd). This prevents users from having to set other environment variables when they switch between areas.

Project_bin allows a single symlink to a user script to be placed in a global PATH. Project_bin then automatically finds that script inside the source controlled area. Different users, or different checkouts will execute the script in their areas. Thus, problems with version mismatch across executing tools are eliminated.

ENVIRONMENT SETUP

To use project_bin, you should make the following settings in your .bashrc or equivalent group file:

   export DIRPROJECT_PREFIX=/prefix     # Any global project prefix
   export PATH=$DIRPROJECT_PREFIX/bin:$PATH

Then for each executable that lives in your source control area that you wish to dispatch to, you create a simlink:

   ln -s project_bin $DIRPROJECT_PREFIX/dir/my_tool

or, instead, make my_tool a script to run project_bin as described in project_bin.

More details in project_bin.

USAGE IN SCRIPTS

Dir::Project may be used three different ways inside scripts.

First, a script may be totally ignorant of Dir::Project. Simply by placing it in a directory that is part of DIRPROJECT_PATH, and creating a symlink from project_bin, it will be executed automatically based on a search starting at the current directory.

Second, a script that is always executed by project_bin can get the root of the checkout by using $DIRPROJECT. Generally I cache the value of DIRPROJECT in a variable called simply $Project.

    BEGIN {
        $Project = $ENV{DIRPROJECT} or die "%Error: Can't determine DIRPROJECT: Call me with project_bin, stopped";
    }
    ....
    my $path_to_file = "$Project/under/project/file/path...";

Third, a script may determine DIRPROJECT itself by using Dir::Project directly. This does not require project_bin to be used to call the program.

    use Dir::Project;
    BEGIN {
        Dir::Project::get_set_project();
        $Project = $ENV{DIRPROJECT} or die "%Error: Can't determine PROJECT: Call this under a project, stopped";
    }
    ....
    my $path_to_file = "$Project/under/project/file/path...";

USAGE IN MAKEFILES

Dir::Project may be called from inside a Makefile. The include will set the DIRPROJECT variable that can then be used to replace absolute paths inside the makefile.

    include $(DIRPROJECT_PREFIX)/lib/project_dir.mk
    # That include will set $(DIRPROJECT) which you can then use
    # to find files underneath the repository checkout.
    ....
    PATHS = $(DIRPROJECT)/path/under/repo

Or, if you only need the DIRPROJECT variable, you can more simply:

   DIRPROJECT := $(shell dir_project --project)

USAGE IN EMACS / VERILOG-MODE

Dir::Project may be used with the AUTOs of Verilog-Mode for Emacs.

Install the contrib/dir-project.el file as described at the top of that file. Restart Emacs.

Now in your source tree create an input.vc file similar to the following:

   -v project/path/to/rtl

The various Verilog module files would then end in a reference to the file you just created:

   // Local Variables:
   // verilog-library-flags:("-f ../../../../input.vc")
   // End:

When AUTOs are expanded the input.vc file will be read. The dir-project.el hook will change the project/ links to an absolute file and that will allow finding any submodules.

An alternative technique is to use $DIRPROJECT/path/to/rtl in the input.vc and setting the DIRPROJECT environment variable. However several EDA tools do not support environment variable expansion in .vc files, thus the above project/ technique.

METHODS

get_set_all(): Set all variables, including get_set_project.
get_set_project(): Set $Project and $ENV{DIRPROJECT}.
makefile(): Create a makefile with the appropriate make code to set DIRPROJECT. This file is then included by make to set the variable.
makefile_cat(): Print the makefile with the appropriate make code to set DIRPROJECT.
program_paths(program=>name): Return a list of paths the program may live at. Uses $DIRPROJECT_PATH and $DIRPROJECT_PREFIX resolved with the current project to determine the list.
program_bin(paths=>\@list): Return the first readable file in the list of paths, or undef if none found.
undefine_all(): Remove all environment variables.

ENVIRONMENT

DIRPROJECT: Points to the top directory of the project source-controlled area. It is created by Dir::Project::get_set_all.
DIRPROJECT_DEBUG: Set when project_bin is invoked with --debug.
DIRPROJECT_PATH: A colon-separated list of directories that program_paths() and project_bin should search for executables within. Generally contains a leading project/ in front of all directories, this will be converted to $DIRPROJECT, though it may also be absolute directory names to search for if the project is not found. Set by the user's .bashrc or similar login script.
DIRPROJECT_PREFIX: A global directory like the --prefix passed to most configure scripts. Used by program_paths() and project_bin to create the default $DIRPROJECT_PREFIX/bin/{program}__not_found link. Set by the user's .bashrc or similar login script.
DIRPROJECT_PROJECTDIREXE: Path and executable for project_dir. Used by project_dir.mk. Generally can be left unset, so it will default to just project_dir (without any directory prefix) so it will be found using PATH.
DIRPROJECT_EXE: The last executable run by project_bin. Set by project_bin.

DISTRIBUTION

Dir-Project is part of the <http://www.veripool.org/> free EDA software tool suite. The latest version is available from CPAN and from <http://www.veripool.org/>.

Copyright 2001-2017 by Wilson Snyder. This package is free software; you can redistribute it and/or modify it under the terms of either the GNU Lesser General Public License Version 3 or the Perl Artistic License Version 2.0.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

AUTHORS

Wilson Snyder <wsnyder@wsnyder.org>