Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Project(3)	      User Contributed Perl Documentation	    Project(3)

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>

SEE ALSO
       project_bin, project_dir

perl v5.24.1			  2017-04-26			    Project(3)

NAME | SYNOPSIS | DESCRIPTION | ENVIRONMENT SETUP | USAGE IN SCRIPTS | USAGE IN MAKEFILES | USAGE IN EMACS / VERILOG-MODE | METHODS | ENVIRONMENT | DISTRIBUTION | AUTHORS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Dir::Project&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help