MMSRC(8)                                                              MMSRC(8)



NAME
       mmsrc - mini msrc, master source tools boot-strap program

SYNOPSIS
       mmsrc  [-z]  [-d  flags] [-f makefile] [-m prereq[:postreq]] [-u login]
       [-y yoke] [hxmd-opts] [utility]
       mmsrc -b [-z] [-d flags] [-f makefile] [-m prereq] [-y yoke] [macro]
       mmsrc -h
       mmsrc -V

COMPLETE
       mmsrc [-lswz] [-B macros] [-C configs]  [-D  name[=value]]  [-d  flags]
       [-E  compares]  [-f  makefile]  [-G  guard]  [-I  dirname]  [-j m4prep]
       [-k key] [-m prereq] [-o attributes]  [-Pjobs]  [-U  name]  [-u  login]
       [-X ex-configs] [-y yoke] [-Y top] [-Z zero-config] [utility]

DESCRIPTION
       All  of  ksb's tools come packaged in a way that allows them to be dis-
       tributed to many hosts to be compiled in platform specific ways.   This
       is  pretty  cool when you have a heterogenous mix of hundreds of hosts.
       Sadly the tools depend on themselves to setup the  environment  to  get
       them built.  So you need a way to fake that environment to boot-strap a
       local installation.  When you have to get ksb's tools started at a  new
       site you need this program.

       This  program  fakes  being  the entire master source tool chain: msrc,
       hxmd, et cetera.  It only fakes this well  enough  to  build  a  master
       source  product locally on a single host.  You'll also need it to build
       mkcmd, explode and the like to get all the others compiled.

       Since mmsrc is often used before the local administrator has configured
       any site specific hxmd configuration data files, mmsrc accepts a simple
       -DHOST=name command-line option to specify the target host as  well  as
       additional  -D  options  to provide required attributes (viz. HOSTTYPE,
       HOSTOS, SHORTHOST, or the like).

       To be as compatible with msrc as  possible  and  to  allow  for  easier
       upgrades,  mmsrc also reads the same configuration files (under -C, -X,
       and -Z) as hxmd.  Any program name (in argv[0]) other than  "mmsrc"  is
       taken  as  a  request  for a zero configuration file with the extension
       ".cf" added to the end.  All of the hxmd host  selection  logic  (under
       -E,  -G,  -B,  -j,  and -Y) is supported to select the target host from
       these files.  (By hxmd-opts we mean only those hxmd  options  specified
       in this paragraph.)

       The same cache directory mapping is allowed as under hxmd when a direc-
       tory is an element of the MAP specification.

       In the absence of a specific host definition mmsrc looks for the  local
       hostname, or "localhost" with the local domain suffix added in any pro-
       vided configs.  When no match is selected from either of  those  names,
       the first host from the hxmd configuration data is selected.

       As  in  msrc,  the  current directory should contain a make recipe file
       with some distinguished macros set.  See msrc(8l) for  the  details  of
       the  macros expected.  Like msrc the value of INTO may be overridden on
       the command-line to force the local platform source cache to  be  in  a
       specific local directory (specify -y INTO=path).

       The  actual compilation or installation of a tool is always done from a
       shadow copy of the master source (called  a  "platform"  copy).   These
       platform  directories  are  usually cached on each remote host, but for
       mmsrc's use they need to be kept on the local machine.  The make  macro
       INTO selects the path to the local cached copy, unless it points to the
       current working directory, which is a fatal error.

       To create the cached copy mmsrc mkdir(2)'s the selected INTO, then  any
       directories  specified  in  SUBDIR, updates and file from SEND that are
       not exactly the same, updates and files from MAP that are  not  exactly
       the  same.   Each  mapped  file is processed through m4 exactly as hxmd
       would; be warned that some of the attribute macros expected  might  not
       be  defined unless they were forced on the command-line (or provided in
       a configuration file).  As in  msrc  options  presented  in  the  files
       listed  in  the  make  macro  HXINCLUDE  are added to the command-line,
       unless -z is presented.

       After the platform cache directory is updated any temporary  files  are
       removed.   Then  mmsrc  changes  directory  to the platform cache, then
       exec's the specified utility.  The default utility is make.   The  spe-
       cial utility name ":" causes mmsrc to exit after constructing the plat-
       form cache.

       To allow the same command-line utility to be quoted the  same  way  for
       both  programs  the  execution  of utility is done via an invocation of
       $SHELL -c.  That means $SHELL  should  be  a  Bourne  shell  compatible
       shell.  This is the best emulation I could think of for msrc's use of a
       remote shell to run its utility.

       The same INCLUDE_CMD, INIT_CMD, PRE_CMD, and POST_CMD attribute  macros
       are  expanded  in  the usual places (see msrc(8l)).  Specify the option
       "-d SPRX" to see  the  whole  process.   The  shell  parameters  (${1},
       ${2}...  ${5}) hold the same values as they would under "local" mode in
       msrc, except for ${1} which holds the same value as ${5} (the value  of
       the make macro "INTO").

       On  the  target host of an msrc build mmsrc may act as a "second stage"
       processor in the platform source directory.  In this case it is used to
       incorporate  local  hxmd configuration data (macro attributes) into the
       delivered structure.  Any secondarily mapped files should be  protected
       from  the outer msrc by explicitly listing their names in the SEND make
       macro, rather than in the MAP macro.

OPTIONS
       If the program is called as mmsrc then no options are forced.  See hxmd
       for detailed option descriptions.

       -b ... macros
              This  replaces  the  FreeBSD  version  of make's -V option.  The
              specified make recipe file is inspected for  the  definition  of
              each macro, which must be a list of white-space separated words.
              The words are output to stdout 1 per line.  This  actually  runs
              make  with the synthetic target "__msync", or one specified with
              -m prereq  (below).   To  avoid  interactions  with  any  update
              actions  specify a prereq target that has no prerequisite depen-
              dencies, I use the force target which canonically has none (viz.
              -m FRC).

       -B macros
              Boolean check as in hxmd.

       -C configs
              Files of hosts and attribute macros, colon separated.

       -d flags
              Debug  flags  we  pass  on to m4.  Some uppercase flags are pro-
              cessed by mmsrc to help debug  configuration  issues.   Use  the
              flag  question-mark  ("?")  for  a  list of supported values and
              their meanings.  As in hxmd only the last (right-most) value  is
              passed on the m4.

       -D name[=value]
              Pass  a  macro definition on to m4.  The macro HOST is inspected
              specially.

       -E compares
              Macro value must satisfy given relation  to  select  hosts,  see
              hxmd.

       -f makefile
              Search  this  makefile  for the same macros msrc requires: INTO,
              MODE, SUBDIR, IGNORE,  SEND,  MAP,  and  HXINCLUDE.   Picking  a
              default value is done exactly as msrc would, see msrc(8l).

       -G guard
              Expressions  to  select  hosts by name, or order selected hosts.
              See hxmd for details.

       -h
              Print only a brief help message.

       -I dirname
              Passed on to m4 to add an  include  directory  name.   When  the
              dirname  is  the  double-dash token (--) it is replaced with the
              first full path from the search list, as hxmd does.

       -m prereq[:postreq]
              Specify the generated make target name to gather  source  files.
              This  target  runs  before  any  files  are copied to INTO.  The
              default is "__msrc" (double-underbar msrc), as it is under msrc.
              The  target  is  appended  to  a copy of the makefile, sometimes
              called the "hook" in the HTML documentation.

              A postreq specification triggers a make update after the process
              is  complete to put away any gathered resources.  This action is
              not taken under -b since it is assumed that the calling  program
              is going to use the files gathered.

              A  specification  of  double-colon (::) turns off postreq, while
              setting prereq to the default value.

       -j m4prep
              Each of the m4prep files are presented to m4 in the command line
              specification  before each processed file, as in hxmd.  Also the
              same file is  included  in  the  host  selection  processing  of
              guards.

       -k key
              Change the merge macro name from "HOST" to key, as in hxmd.

       -u login
              Passes  the  specified  login on to m4 in the macro ENTRY_LOGIN.
              This is just for better command-line compatibility with msrc.

       -U name
              Passed on to m4, to remove a macro definition.

       -V
              Show only version information.

       -w
              For command-line compatibility with msrc this flag allows only a
              single  updated  of the prereq token. The new recipe uses xclate
              to fetch the values plundered from the master makefile, so  this
              only works after the base package is installed.

       -X ex-configs
              Add attribute macro data to defined hosts, colon separated.

       -y yoke
              As in msrc this option passes a command-line word on to the make
              instance that plunders the makefile.  This is  largely  used  to
              tune  the  recipe  file's  macro definitions to override INTO or
              even MODE.  For recursive recipes  when  either  msrc  or  mmsrc
              might  be  used  to  drive  a makefile, a macro may be needed to
              select which to call.  This option must then be used to pass the
              present  value  of  that  macro on to the next level.  The usual
              name for that macro is "MSRC", the  default  value,  while  site
              specific, is usually "msrc".

       -Y top
              M4  commands included at the top of the guard processing, before
              guard is processed for each host.

       -z
              Do not interpolate the options specified in the file  listed  in
              the  make  macro  HXINCLUDE  into  our  command-line.  Not every
              option to hxmd is allowed to mmsrc, so sometimes suppressing the
              value  in the makefile is a good idea.  Alternately try using -y
              to change HXINCLUDE.

       -Z zero-config
              Configuration file(s) to set default attribute macro values.

COMPATIBILITY
       These options are consumed for better command-line  compatibility  with
       msrc.

       -l
              This option expands to "-y MODE=local" in an attempt to override
              any recipe definition which sets MODE to remote.

       -Pjobs
              Consumed and ignored.

       -s
              As there is no slow-start logic in mmsrc this  is  ignored  com-
              pletely, see hxmd.

ENVIRONMENT
       This  program  doesn't  consult the environment as much as msrc, but it
       does source a local definition  files  (ENTRY_DEFS)  if  the  attribute
       macro  is  defined  for the selected host.  Usually the inherited build
       environment is adequate because we are driven from a local  shell  (not
       from an remote shell).

       The  environment  variables HOME, SHELL, TMPDIR, and PATH are consulted
       for their traditional purposes.  As well as HXMD_LIB, which is used  as
       hxmd does to set an explicit search list for command-line configuration
       files.

       The environment variable MMSRC_PASS  is  used  in  much  the  same  why
       HXMD_PASS  is used to send options from msrc to hxmd.  But in this case
       mmsrc executes a new  copy  of  itself  to  process  the  options  from
       Msrc.hxmd.   Don't set this variable in the environment unless you mean
       to ignore the local hxmd options files.

EXAMPLES
       mmsrc -V
              The standard  version  information  for  mmsrc  is  extended  to
              include  the specific versions of the modules extracted from the
              programs it emulates: these have 2  spaces  before  the  version
              string.

       mmsrc -Clocal.cf -B MSRC  :
              Construct a platform cache for the (only) host in local.cf which
              has the macro "MSRC" defined.  If  this  host's  name  has  that
              macro  defined  it will be selected in preference to any others.
              Note that no utility is actually executed due to the colon (":")
              specification.

       mmsrc -Clocal.cf -B MSRC  ls -last | less
              Same  as  above,  but  run ls(1) to display the created platform
              cache.

       mmsrc -DHOST=lv426 -DHOSTTYPE=SUN5  make all install clean
              Build this program for the host lv426  with  the  platform  type
              "SUN5", install the program and cleanup after that.

       mmsrc -DHOST=nostromo -DHOSTTYPE=LINUX  ${SHELL} -i
              Configure  the platform cache for "nostromo", then start a shell
              in the updated directory.  I usually set $PS1 for that  command.

       mmsrc -Cadm.cf -y INTO=/tmp/boot.mmsrc  make all
              While  searching the makefile for macros build the target prereq
              to synchronize the local copy. Then configure a  platform  cache
              for  the  local  hostname  (attributes from adm.cf) in the local
              directory /tmp/boot.mmsrc, and run make with the target "all".

       mmsrc -d '?'
              Display any on-line help for the debug flags.

       mmsrc -- make all
              Depend on the make(1) macro HXINCLUDE to specify the  configura-
              tion  data  for  host selection and macro definition.  The macro
              might be set to a file  containing  any  of  the  above  example
              selection options, e.g "-Clocal.cf -B MSRC".  It is poor form to
              put options to xapply(1l), xclate(1l), or ptbw(1l) in this macro
              as they won't work under mmsrc, but might under msrc (as a side-
              effect of how they are read).

       mmsrc -b INTO
              Output the value of the  make  macro  INTO.   This  is  used  by
              msync(8l) from the revision control tool-chain.  In fact that is
              why the default prereq token under -b is double-underbar  msync.

NOTES
       Sometimes  shell start-up variables reset the environment.  For example
       your .kshrc my set $PATH.  This is only a problem if the build  process
       has  set an explicit path to find a build tool, then your shell startup
       may reset the PATH so the build process fails.  It is a  good  idea  to
       check your shell startup if a build fails because it cannot find a pro-
       gram it just built.

BUGS
       If you count the fact that you need such a program in the first  place,
       then you've found one.

       Files with only mode changes are not chmod'd in the platform cache.  To
       fix this just remove the platform cache (or  the  impacted  files)  and
       push  again.   It  didn't  seem worth the cost of building a dependency
       link to rsync(1), or to implementing it in shell.

       When the local hostname isn't listed in the  hxmd  configuration  files
       the use of the first host matched might be a bug: use an explicit -D to
       pick the one you meant.  On the other hand it might be a bug that  hxmd
       won't honor the -D of HOST to pick a host by name.

       This  program  doesn't  emulate  xapply or any related wrappers at all.
       Use of percent escapes is not supported in  the  utility  command-line.
       Also the -z option is a bit of a kludge.

       There  is  no ideal way to cleanup the cached platform directory.  Just
       remove the whole tree when you are done.  Or try something like:
              mmsrc ... sh -c "eval cd / \\; rm -r \'pwd\'"

AUTHOR
       KS Braunsdorf
       NonPlayer Character Guild
       mmsrc at no-SPAM here ksb dot-here npcguild.org

SEE ALSO
       sh(1), ksh(1), hxmd(8l), msrc(8l), m4(1), execve(2), environ(7), cp(1),
       msync(8l), efmd(8l), level2s(8l), mkcmd(1l), explode(1l), chmod(2)



                                     LOCAL                            MMSRC(8)

NAME | SYNOPSIS | COMPLETE | DESCRIPTION | OPTIONS | COMPATIBILITY | ENVIRONMENT | EXAMPLES | NOTES | BUGS | AUTHOR | SEE ALSO