NAME

Dir::Project - Project Environment determination

SYNOPSIS

  use Dir::Project;
  Dir::Project::get_set_all();

DESCRIPTION

the Dir::Project manpage provides a way to locate a source-controlled directory (CVS, Subversion, Perforce, etc) using only the current working directory (cd). This prevents users from having to set other environment variables when they switch between areas, and allows scripts and such inside the directory to be executed without changing the user's PATH.

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 the make manpage code to set DIRPROJECT. This file is then included by make to set the variable.
makefile_cat(): Print the makefile with the appropriate the make manpage 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.

USAGE IN SCRIPTS

the Dir::Project manpage 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 the cwd.

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 me with project_bin, stopped";
    }
    ....
    my $path_to_file = "$Project/under/project/file/path...";

USAGE IN MAKEFILES

the Dir::Project manpage 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
    ....
    PATHS = $(DIRPROJECT)/...

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 the project_bin manpage 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 the project_bin manpage to create the default $DIRPROJECT_PREFIX/bin/{program}__not_found link. Set by the user's .bashrc or similar login script.
DIRPROJECT_EXE: The last executable run by the project_bin manpage. Set by the project_bin manpage.

DISTRIBUTION

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

Copyright 2001-2007 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 or the Perl Artistic License.

AUTHORS

Wilson Snyder <wsnyder@wsnyder.org>