[GRASS5] Environment variable listings...

GRASS GRASS developer
1

Do you think people would find it useful if g.gisenv could list all of
the known environment variables with a bit of information about them?

I've hacked my copy of g.gisenv to do this via an "-l" flag. Output is
like:

----------------------<snippet>----------------------------------
VARIABLE :: GRASS_FP_DOUBLE [(nil)]
DESCRIPTION :: Default type of floating point representation for floating point rasters.
DOMAIN :: DCELL_TYPE | FCELL_TYPE
EXAMPLE :: GRASS_FP_DOUBLE=FCELL_TYPE

Press Enter to continue ('q' to quit)>

VARIABLE :: GRASS_HEIGHT [2400]
DESCRIPTION :: Define height of CELL driver output
DOMAIN :: Positive integer
EXAMPLE :: GRASS_HEIGHT=480

...
----------------------<snippet>----------------------------------

It pauses between entries iff isatty(1) is true. It does not interfere
with the get/set behavior currently in place.

Seems it's never easy enough to figure out what environment variables
are available for controlling behaviors... Developer's can easily add
to the struct array if there's a module that recognizes a certain
variable and it's not yet "registered".

Opinions?

--
Eric G. Miller <egm2@jps.net>

2

Eric G. Miller wrote:

Do you think people would find it useful if g.gisenv could list all of
the known environment variables with a bit of information about them?

I've hacked my copy of g.gisenv to do this via an "-l" flag. Output is
like:

[snip]

Seems it's never easy enough to figure out what environment variables
are available for controlling behaviors... Developer's can easily add
to the struct array if there's a module that recognizes a certain
variable and it's not yet "registered".

Opinions?

Adding this to g.gisenv might further confuse users regarding the
distinction between GRASS variables ($GISRC) and environment variables
(getenv()). It might be better to have a separate program.

--
Glynn Clements <glynn.clements@virgin.net>

3

On Fri, Aug 10, 2001 at 12:39:49PM +0100, Glynn Clements wrote:

Eric G. Miller wrote:

> Do you think people would find it useful if g.gisenv could list all of
> the known environment variables with a bit of information about them?
>
> I've hacked my copy of g.gisenv to do this via an "-l" flag. Output is
> like:

[snip]

> Seems it's never easy enough to figure out what environment variables
> are available for controlling behaviors... Developer's can easily add
> to the struct array if there's a module that recognizes a certain
> variable and it's not yet "registered".
>
> Opinions?

Adding this to g.gisenv might further confuse users regarding the
distinction between GRASS variables ($GISRC) and environment variables
(getenv()). It might be better to have a separate program.

These are GRASS variables (GISRC). That's what g.gisenv manipulates.
Normal environment variables are available with "env" command. The
proposal would only have those GRASS variables that are settable (and
meaningful) in GISRC (~/.grassrc5). "g.gisenv" manipulates that file
directly with the "set=" argument.

--
Eric G. Miller <egm2@jps.net>

4

Eric G. Miller wrote:

> > Do you think people would find it useful if g.gisenv could list all of
> > the known environment variables with a bit of information about them?
> >
> > I've hacked my copy of g.gisenv to do this via an "-l" flag. Output is
> > like:
>
> [snip]
>
> > Seems it's never easy enough to figure out what environment variables
> > are available for controlling behaviors... Developer's can easily add
> > to the struct array if there's a module that recognizes a certain
> > variable and it's not yet "registered".
> >
> > Opinions?
>
> Adding this to g.gisenv might further confuse users regarding the
> distinction between GRASS variables ($GISRC) and environment variables
> (getenv()). It might be better to have a separate program.

These are GRASS variables (GISRC). That's what g.gisenv manipulates.
Normal environment variables are available with "env" command. The
proposal would only have those GRASS variables that are settable (and
meaningful) in GISRC (~/.grassrc5). "g.gisenv" manipulates that file
directly with the "set=" argument.

From src/display/devices/CELL/Graph_Set.c:

    if (NULL != (p = getenv ("GRASS_WIDTH")))
...
    if (NULL != (p = getenv ("GRASS_HEIGHT")))

In this context, GRASS_WIDTH and GRASS_HEIGHT are environment
variables. Whether these variables appear in $GISRC or what values
they have there is irrelevant to the CELL driver. All that matters is
whether they are defined in the environment, and with what values.

The potential for confusion arises because $GISBASE/etc/Init.sh
executes "eval `g.gisenv`" under some circumstances (if GRASS_GUI is
"text", or if it falls back to "text"), which will cause the settings
in $GISRC to be reflected into the environment.

However, if the contents of $GISRC and/or the environment are
subsequently modified so, that the two differ, the version which is
used depends upon whether the program uses getenv() or G__getenv().

--
Glynn Clements <glynn.clements@virgin.net>

5

On Fri, Aug 10, 2001 at 09:41:23PM +0100, Glynn Clements wrote:
[snip]

> These are GRASS variables (GISRC). That's what g.gisenv manipulates.
> Normal environment variables are available with "env" command. The
> proposal would only have those GRASS variables that are settable (and
> meaningful) in GISRC (~/.grassrc5). "g.gisenv" manipulates that file
> directly with the "set=" argument.

>From src/display/devices/CELL/Graph_Set.c:

    if (NULL != (p = getenv ("GRASS_WIDTH")))
...
    if (NULL != (p = getenv ("GRASS_HEIGHT")))

Well, that looks like a bug to me. I don't know why it wouldn't be
using the G__getenv() routine. IMHO, *all* GRASS specific environment
variables belong in ~/.grassrc5. There's no reason user's should have
to pollute their normal environment with variables that are meaningless
outside the GRASS context.

In this context, GRASS_WIDTH and GRASS_HEIGHT are environment
variables. Whether these variables appear in $GISRC or what values
they have there is irrelevant to the CELL driver. All that matters is
whether they are defined in the environment, and with what values.

The potential for confusion arises because $GISBASE/etc/Init.sh
executes "eval `g.gisenv`" under some circumstances (if GRASS_GUI is
"text", or if it falls back to "text"), which will cause the settings
in $GISRC to be reflected into the environment.

I still don't see the problem (other than what I stated above). If the
variable doesn't exist in ~/.grassrc5, "eval `g.gisenv`" won't change
that fact. The only change I was proposing, was an ability to get a
listing of "possible" environment variables with a little bit of
explanation. I can't help it that there are code segments which don't
use the GRASS environment variable interface (they should unless it's a
generic well-defined environment variable like $EDITOR).

However, if the contents of $GISRC and/or the environment are
subsequently modified so, that the two differ, the version which is
used depends upon whether the program uses getenv() or G__getenv().

Well, then code using getenv() should change. This potential *already*
exists. User's can screw up their location settings as well. It
doesn't make any sense to have some GRASS specific "environment"
variable specified in ~/.grass.bashrc or ~/.bashrc (or whatever) and
have some others in ~/.grassrc5 and accessed via the libgis API.

I can leave out "environment" variables that aren't accessed via the
libgis API (I wasn't aware that the CELL driver didn't use it). But I
thought it might be generally useful just to be able to type
"g.gisenv -l" and get a listing of all the possible "environment"
variables that effect GRASS modules *and* what they mean, what can be
specified, and an example. If user's can't even find them, then why
have most of 'em?

I guess what we need here is a little consistency. Either ~/.grassrc5
contains all the settable environment variables that are GRASS specific,
or it shouldn't contain any. Right now, there's apparently a mixture.

--
Eric G. Miller <egm2@jps.net>

6

Analysing the results of a recursive grep indicate that:

1. The following variables are accessed using G__getenv() (including
use of G_getenv()):

DATABASE
DB_DATABASE
DB_DRIVER
DB_KEYCOL
DB_LOCATION
DB_PASSWORD
DB_USER
DIGITIZER
GISBASE
GISDBASE
LOCATION_NAME
MAPSET
MONITOR
Nviz_AutoSurfColors
PAINT
PAINTER
PAINT_DRIVER
PAINT_DRIVER_SHELL
PG_DBASE
PG_HOST
PSPAINTER

2. The following variables are accessed using getenv():

ANGLE
BAUD
CMAP_SIZE
CODECENTER
DBMSCAP
DEB
DEBUG
DISPLAY
DPG_LOCK
DUMP
ELEMENT_LIST
ENDPANEL
FORCE_GRASS3_COLORS
GDAL_HOME
GISBASE
GISRC
GIS_LOCK
GMPEG_SIZE
GRAPH
GRASS_BACKGROUNDCOLOR
GRASS_FP_DOUBLE
GRASS_GNUPLOT
GRASS_HEIGHT
GRASS_HTMLFILE
GRASS_HTMLMAXPOINTS
GRASS_HTMLMINBBOX
GRASS_HTMLMINDIST
GRASS_HTMLTYPE
GRASS_ORGANIZATION
GRASS_PAN_THRESHOLD
GRASS_PNGFILE
GRASS_STDERR
GRASS_TRANSPARENT
GRASS_WIDTH
GTUNE_VSUP_RAM
HEIGHT
HOME
LOCATION
LOCATION_NAME
MAPLP
NODUMP
NO_DRAW
NPIXELS
PAINT_HEADER
PAINT_TRACE
PREVIEW_BACKGROUND
PROJ_LIB
QUALITY
RASTERFILE
SHORT
SPAG_THRESH
SPRINT_COMMAND
SQLBASE_DRIVER_STDERR
STARTPANEL
TERM
TRANSPARENT
USER
WIDTH
XDRIVER_PRIVATE_CMAP
XGANIM_SIZE

3. The following variables are accessed using both methods:

GISBASE
LOCATION_NAME

Summary: 21 using G__getenv() and 60 using getenv(), with 2 variables
occurring in both categories.

I guess what we need here is a little consistency. Either ~/.grassrc5
contains all the settable environment variables that are GRASS specific,
or it shouldn't contain any. Right now, there's apparently a mixture.

Due to the way in which the environment works, variables which are
changed by specific commands, (e.g. MONITOR and "d.mon select=...")
cannot be implemented as environment variables.

OTOH, some of the above variables have to be environment variables.
E.g. the value of TERM has to be taken from the environment, and HOME
and USER should probably be treated likewise.

In other cases, it's largely irrelevant, but only because GRASS is
currently tied to the "session" model, and doesn't permit a user to
run multiple GRASS sessions simultaneously. If this were to change, in
most cases there would be an advantage to using environment variables,
as they can be set on a per-process basis.

--
Glynn Clements <glynn.clements@virgin.net>

7

On Sat, Aug 11, 2001 at 11:51:08AM +0100, Glynn Clements wrote:

Analysing the results of a recursive grep indicate that:

[snip]

Summary: 21 using G__getenv() and 60 using getenv(), with 2 variables
occurring in both categories.

> I guess what we need here is a little consistency. Either ~/.grassrc5
> contains all the settable environment variables that are GRASS specific,
> or it shouldn't contain any. Right now, there's apparently a mixture.

Due to the way in which the environment works, variables which are
changed by specific commands, (e.g. MONITOR and "d.mon select=...")
cannot be implemented as environment variables.

Yes.

OTOH, some of the above variables have to be environment variables.
E.g. the value of TERM has to be taken from the environment, and HOME
and USER should probably be treated likewise.

Yes.

In other cases, it's largely irrelevant, but only because GRASS is
currently tied to the "session" model, and doesn't permit a user to
run multiple GRASS sessions simultaneously. If this were to change, in
most cases there would be an advantage to using environment variables,
as they can be set on a per-process basis.

I think many on this list will agree we don't really like the current
session management system. Besides this bit about the environment,
the other annoyances include:

  * Only allowed to run 1 session at a time
  * Uses "global" mapset lock rather than more appropriate fcntl() file
     locking (as needed).
  * Inability to change GISDBASE/LOCATION/MAPSET on the fly.
  * Doesn't play well with multiuser shared data scenario.

I'll not commit the g.gisenv change, since obviously the listing would
be less useful than I originally thought.

--
Eric G. Miller <egm2@jps.net>