


DMAKE(1)                  User Commands                  DMAKE(1)



NAME
     dmake - DistributedMake

SYNOPSIS
     dmake [-c dmake_rcfile] [-g dmake_group] [-j dmake_max_jobs]
     [-o dmake_odir]

DESCRIPTION
     Note: This man page supplements the make utility man page.

     DMake is part of the Sun WorkShop TeamWare  product.   DMake
     (DistributedMake) parses your makefiles and determines which
     target can be built concurrently, and distributes the  build
     of those targets over a number of hosts set by you.

     If you use the standard  make  utility,  the  transition  to
     DMake  requires  little if any alteration to your makefiles.
     DMake is a superset of the make utility. With nested  makes,
     if  a  top-level  makefile  calls  "make",  you  need to use
     $(MAKE).

     You execute dmake on a "DMake host" and distribute "jobs" to
     "build  servers."  You can also distribute jobs to the DMake
     host, in which case the DMake  host  also  becomes  a  build
     server.  DMake  distributes  jobs  based on makefile targets
     that DMake determines (based on your makefiles) can be built
     concurrently.

     You can use any machine as a build  server  as  long  as  it
     meets the following requirements:

          -From the DMake host (the machine you  are  using)  you
          must  be  able to use rsh, without being prompted for a
          password, to remotely execute  commands  on  the  build
          server. For example:

               demo% rsh <machine_name> which dmake
               /opt/SUNWspro/bin/dmake
          The rsh must be "clean", with no additional output.

          -The bin directory  in  which  the  DMake  software  is
          installed must be accessible from the build server.

          -The bin directory  in  which  the  DMake  software  is
          installed must be in your execution path when logged in
          on the build server. Be sure this directory is added to
          the  PATH variable in your .cshrc file (or equivalent),
          not in your .login file. You can verify this using  the
          command described above.  -The source hierarchy you are
          building must be accessible from the build server, (see
          below).




SunOS 5.5          Last change: 20 March 1996                   1






DMAKE(1)                  User Commands                  DMAKE(1)



     From the DMake host you can control which build servers  are
     used  and  how  many  DMake  jobs are allotted to each build
     server. The number of DMake jobs that can  run  on  a  given
     build server can also be limited on that server.

OPTIONS
     -c dmake_rcfile
          Specifies an alternate runtime configuration file.  The
          default runtime configuration file is $(HOME)/.dmakerc.

     -g dmake_group
          Specifies the name of the build server group  to  which
          jobs  are distributed.  You define server groups in the
          runtime configuration file.  The default  server  group
          is the first group in the runtime configuration file.

     -j dmake_max_jobs
          Specifies the maximum total number  of  jobs  that  are
          distributed  to the specified group of build servers in
          the runtime configuration  file.  The  default  maximum
          number  of jobs is the sum of all the specified jobs in
          a build server group. The jobs are subtracted from,  or
          added  to,  hosts  by 1 in the order they appear in the
          runtime configuration file.  For example, if  all  jobs
          specified in the runtime configuration file total 8:

               host earth { jobs = 3 }
               host mars  { jobs = 5 }

          and dmake_max_jobs is specified as 11, DMake adds three
          more  jobs  to the current total maximum number of jobs
          (which is eight) as follows:

               host earth { jobs = 5 }
               host mars  { jobs = 6 }

          Also, if dmake_max_jobs is specified as 4,  DMake  sub-
          tracts 4 jobs (from the original eight) as follows:

               host earth { jobs = 1 }
               host mars  { jobs = 3 }


     -m {serial | parallel | distributed}
          Specify one of the following key words:

          serial      Causes DMake to behave  like  the  standard
                      serial version of make.

          parallel    Causes DMake to execute jobs  to  only  the
                      DMake  host.  This behavior is identical to
                      the ParallelMake program  distributed  with



SunOS 5.5          Last change: 20 March 1996                   2






DMAKE(1)                  User Commands                  DMAKE(1)



                      TeamWare 1.x.

          distributed Causes DMake to behave in fully distributed
                      mode. This is the DMake default.

     -o dmake_odir
          Specifies a common physical directory  that  DMake  can
          write temporary output files to and read temporary out-
          put files from. The directory  used  is  $(HOME)/.dmake
          and  this  or whichever directory is specified, must be
          visible to all build servers.  Use this option only  if
          the  $(HOME)  directory  on  your  local  host  and the
          $(HOME) directory on all of your remote hosts  are  NOT
          the  same  physical  $(HOME) directory.  For example, a
          root user would use this option.


     Note: These  options  and  the  environment  variables   and
           makefile  macros  described  later  in  this  man page
           modify the same behavior. Their order of precedence is
           defined as:

           1. Command-line options

           2. Makefile macros

           3. Environment variables

           4. DMake default

USE
  Special-purpose Targets
     DMake allows targets to be built concurrently on a number of
     build servers.  Concurrent processing can greatly reduce the
     time required to build a large system or project. DMake sup-
     plies  the special makefile targets .PARALLEL, .NO_PARALLEL,
     and .WAIT for controlling concurrency and timing.

     .NO_PARALLEL:    Use this target to indicate  which  targets
                      are to be processed serially.

     .PARALLEL:       Use this target to indicate  which  targets
                      are to be processed in parallel.

     .WAIT            When you specify this target  in  a  depen-
                      dency list, DMake waits until the dependen-
                      cies that precede it  are  finished  before
                      processing  those  that  follow,  even when
                      processing is parallel.

     Makefiles that you write using these targets remain compati-
     ble  with  the  standard  version  of  make distributed with



SunOS 5.5          Last change: 20 March 1996                   3






DMAKE(1)                  User Commands                  DMAKE(1)



     Solaris 1.x and Solaris 2.x.  Standard  make  accepts  these
     targets without error (and without action).

     See the Sun WorkShop TeamWare User's Guide for more informa-
     tion  about  modifications you can make to makefiles for use
     with DMake.



  Controlling DMake Jobs
     The distribution of DMake jobs is controlled in two ways:

          1. A DMake  user  on  a  DMake  host  can  specify  the
          machines  they  want  to  use  as build servers and the
          number of jobs they want to distribute  to  each  build
          server.

          2.   The   owner   (a   user   that   can   alter   the
          /etc/opt/SPROdmake/dmake.conf  file ) on a build server
          can control the maximum total number of DMake jobs that
          can be distributed to that build server.

  The DMake Host
     When DMake begins execution it searches for a runtime confi-
     guration  file  to know where to distribute jobs. Generally,
     this file is located in your home  directory  on  the  DMake
     host  and is named .dmakerc.  DMake searches for the runtime
     configuration file in the following  locations  and  in  the
     following order:

     1.  The path name you specify on the command line using  the
         -c option

     2.  The  path  name  you  specify  using  the   DMAKE_RCFILE
         makefile macro

     3.  The  path  name  you  specify  using  the   DMAKE_RCFILE
         environment variable

     4.  $(HOME)/.dmakerc

     If a runtime configuration file is not found, DMake switches
     to  parallel  mode and distributes two jobs (the default) to
     the DMake host. You can change this using the -j option,  or
     DMAKE_MAX_JOBS.

     The runtime configuration file may contain a list  of  build
     servers  and the number of jobs you want distributed to each
     build server. The following is a sample of a simple  runtime
     configuration file:





SunOS 5.5          Last change: 20 March 1996                   4






DMAKE(1)                  User Commands                  DMAKE(1)



          # My machine. This entry causes DMake to distribute to it
          falcon { jobs = 1 }
          hawk
          eagle { jobs = 3 }
          # Manager's machine. She's usually at meetings
          heron { jobs = 4 }
          avocet

     The entries: falcon, hawk,  eagle,  heron,  and  avocet  are
     listed as build servers.

     You can specify the number of jobs you want  distributed  to
     each build server. The default number of jobs is two.

     Any line that begins with the "#" character  is  interpreted
     as a comment.

     Note: This list of build servers includes  falcon  which  is
           also the DMake host. The DMake host can also be speci-
           fied as a build server. If you do not  include  it  in
           the runtime configuration file, no DMake jobs are dis-
           tributed to it.

     You can also construct groups of build servers in  the  run-
     time  configuration  file. This provides you with the flexi-
     bility of easily switching between different groups of build
     servers  as  circumstances  warrant.   For  instance you may
     define a different group of build servers for  builds  under
     different  operating  systems, or on groups of build servers
     that have special software installed  on  them.   The  build
     servers  must be all the same architecture and have the same
     SunOS installed.

     The following runtime configuration file contains groups:

     earth                   { jobs = 2 }
     mars                    { jobs = 3 }

     group lab1 {
                    host falcon    { jobs = 3 }
                    host hawk
                    host eagle     { jobs = 3 }
     }

     group lab2 {
                    host heron
                    host avocet    { jobs = 3 }
                    host stilt     { jobs = 2 }


     group labs {
                    group lab1



SunOS 5.5          Last change: 20 March 1996                   5






DMAKE(1)                  User Commands                  DMAKE(1)



                    group lab2
     }

     group sunos5.x {
                    group labs
                    host jupiter
                    host venus     { jobs = 2 }
                    host pluto     { jobs = 3 }
     }

     Formal groups are specified by  the  "group"  directive  and
     lists of their constituents are delimited by braces ({}).

     Build servers that are constituents of groups are  specified
     by the optional "host" directive.

     Groups can be constituents of other groups.

     Individual build servers can be listed in runtime configura-
     tion  files  that  also contain groups of build servers.  In
     this case DMake treats these build servers  as  constituents
     of the unnamed group.

     DMake distributes jobs to a single group of hosts  specified
     by the following list and in precedence from 1 to 4.

     1. The group specified on the command-line as an argument to
        the -g option

     2. The group specified by the DMAKE_GROUP makefile macro

     3. The group specified by the DMAKE_GROUP environment  vari-
        able

     4. The first formal group listed in the  runtime  configura-
        tion file

  The Build Server
     The /etc/opt/SPROdmake/dmake.conf file  is  located  in  the
     file  system  of build servers. Use this file to specify the
     following:

     Required
     -The maximum total number of DMake jobs (from all users) that can
      run concurrently on that build server.
     Optional
     -The /usr/bin/ priority under which all DMake jobs are to be run.

     The following is a sample of a dmake.conf file:
          max_jobs: 8
          _prio: 5




SunOS 5.5          Last change: 20 March 1996                   6






DMAKE(1)                  User Commands                  DMAKE(1)



     This file sets the maximum number of DMake jobs permitted to
     run on that build server (from all DMake users) to be eight.
     You can change the priority of the jobs to be run  by  using
     the nice_prio command. See nice(1).

     Note: If the  /etc/opt/SPROdmake/dmake.conf  file  does  not
     exist  on  a  build server, no DMake jobs will be allowed to
     run on that server.

ENVIRONMENT/MACROS
     The following can be defined as either environment variables
     or makefile macros:

     DMAKE_RCFILE             Defines an alternate runtime confi-
                              guration  file. The default runtime
                              configuration        file        is
                              $(HOME)/.dmakerc .

     DMAKE_GROUP              Defines  the  name  of  the   build
                              server group to which jobs are dis-
                              tributed. Server groups are defined
                              in  the runtime configuration file.
                              The default  server  group  is  the
                              first  group  in the runtime confi-
                              guration file.

     DMAKE_MAX_JOBS           Defines the maximum total number of
                              jobs  that  are  distributed to the
                              specified group of build servers in
                              the runtime configuration file. The
                              default maximum number of  jobs  is
                              the  sum  of all the specified jobs
                              in a build server group.  The  jobs
                              are  subtracted  from, or added to,
                              hosts by 1 in the order they appear
                              in  the runtime configuration file.
                              See the -j option in this man  page
                              for an example.

     DMAKE_MODE               May contain one  of  the  following
                              key words:

                              serial      Causes DMake to  behave
                                          like    the    standard
                                          serial version of make.

                              parallel    Causes DMake to distri-
                                          bute  jobs  to only the
                                          DMake    host.     This
                                          behavior  is  identical
                                          to   the   ParallelMake
                                          program     distributed



SunOS 5.5          Last change: 20 March 1996                   7






DMAKE(1)                  User Commands                  DMAKE(1)



                                          with TeamWare 1.x.

                              distributed Causes DMake to  behave
                                          in   fully  distributed
                                          mode. This is the DMake
                                          default.

     DMAKE_ODIR               Defines a common physical directory
                              that DMake can write temporary out-
                              put files  to  and  read  temporary
                              output   files   from.    Use  this
                              environment  variable,  or   macro,
                              only  if  the  $(HOME) directory on
                              your local  host  and  the  $(HOME)
                              directory  on  all  of  your remote
                              hosts are  NOT  the  same  physical
                              $(HOME)  directory.  For example, a
                              root user would use this option.

FILES
     $(HOME)/.dmakerc    The default runtime configuration  file.
                         Contains  the names of build servers and
                         groups of build servers.

     /etc/opt/SPROdmake/dmake.conf
                         Located on build servers, this  file  is
                         used to specify the maximum total number
                         of jobs that can be distributed to it by
                         all  DMake  users.   It  is also used to
                         specify the /usr/bin/nice  priority  all
                         DMake jobs are to be run under.

SEE ALSO
     Sun WorkShop TeamWare User's Guide.

DIAGNOSTICS
     See the Sun WorkShop TeamWare User's Guide  for  a  complete
     list of error and warning messages and possible remedies.

















SunOS 5.5          Last change: 20 March 1996                   8



