Welcome to Linux Knowledge Base and Tutorial
"The place where you learn linux"
Child Fund

 Create an AccountHome | Submit News | Your Account  

Tutorial Menu
Linux Tutorial Home
Table of Contents

· Introduction to Operating Systems
· Linux Basics
· Working with the System
· Shells and Utilities
· Editing Files
· Basic Administration
· The Operating System
· The X Windowing System
· The Computer Itself
· Networking
· System Monitoring
· Solving Problems
· Security
· Installing and Upgrading
· Linux and Windows

Glossary
MoreInfo
Man Pages
Linux Topics
Test Your Knowledge

Site Menu
Site Map
FAQ
Copyright Info
Terms of Use
Privacy Info
Disclaimer
WorkBoard
Thanks
Donations
Advertising
Masthead / Impressum
Your Account

Communication
Feedback
Forums
Private Messages
Surveys

Features
HOWTOs
News Archive
Submit News
Topics
User Articles
Web Links

Google
Google


The Web
linux-tutorial.info

Who's Online
There are currently, 210 guest(s) and 0 member(s) that are online.

You are an Anonymous user. You can register for free by clicking here

  

distcc



SYNOPSIS

       distcc <compiler> [COMPILER OPTIONS]

       distcc [COMPILER OPTIONS]

       <compiler> [COMPILER OPTIONS]


DESCRIPTION

       distcc  distributes  compilation  of C code across several
       machines on a network.  distcc should always generate  the
       same  results as a local compile, is simple to install and
       use, and is often much faster than a local compile.

       distcc sends the complete  preprocessed  source  code  and
       compiler arguments across the network for each job, so the
       machines do not need to share a filesystem, have the  same
       headers  or  libraries  installed,  or  have  synchronized
       clocks.

       Compilation is driven by a "client" machine, which is typ­
       ically  the developer's workstation or laptop.  The distcc
       client runs on this machine, as does make, the  preproces­
       sor,  the  linker,  and other stages of the build process.
       Any number of "volunteer"  machines  help  the  client  to
       build  the  program,  by  running the distccd(1) daemon, C
       compiler and assembler as required.

       distcc can run across either TCP sockets (on port 3632  by
       default), or through a tunnel command such as ssh(1).  For
       TCP connections the volunteers  must  run  the  distccd(1)
       daemon either directly or from inetd.  For SSH connections
       distccd me be installed but should not  be  listening  for
       connections.

       TCP  connections  should  only  be used on secure networks
       because there is no user authentication or  protection  of
       source  or object code.  SSH connections are typically 25%
       slower  because  of  processor  overhead  for  encryption,
       although  this can vary greatly depending on CPUs, network
       and the program being built.

       distcc is intended to be used with GNU Make's  -j  option,
       which   runs   several  compiler  processes  concurrently.
       distcc spreads the jobs across both local and remote CPUs.
       Because  the overhead of distcc and network traffic is low
       relative to the work of running  the  compiler,  this  can
       greatly  reduce  build time.  The -j value should normally
       be set to about twice the number  of  available  CPUs,  to
       allow  for  some  tasks  being blocked waiting for disk or
       network IO.  distcc can also work with other build control
       tools such as SCons.


       4      Build!
              $ make -j8 CC=distcc


HOW IT WORKS

       distcc only ever runs the compiler and assembler remotely.
       The  preprocessor must always run locally because it needs
       to access various header files on the local machine  which
       may  not be present, or may not be the same, on the volun­
       teer.  The linker similarly needs to examine libraries and
       object files, and so must run locally.

       The  compiler  and assembler take only a single input file
       (the preprocessed source) and produce a single output (the
       object  file).   distcc  ships  these two files across the
       network  and  can  therefore  run  the  compiler/assembler
       remotely.

       Fortunately, for most programs running the preprocessor is
       relatively cheap, and  the  linker  is  called  relatively
       infrequent, so most of the work can be distributed.

       distcc  examines  its  command  line to determine which of
       these phases are being invoked, and whether the job can be
       distributed.


OPTION SUMMARY

       Most  options passed to distcc are interpreted as compiler
       options.  Two options are understood by distcc itself:

       --help Displays summary instructions.

       --version
              Displays the distcc client version.


INSTALLING DISTCC

       There are three different ways to  call  distcc,  to  suit
       different circumstances:

              distcc  can be installed under the name of the real
              compiler, to intercept calls to  it  and  run  them
              remotely.   This  "masqueraded"  compiler  has  the
              widest compatibility with  existing  source  trees,
              and  is  convenient when you want to use distcc for
              all compilation.  The fact  that  distcc  is  being
              used is transparent to the makefiles.

              distcc  can be prepended to compiler command lines,
              such as "distcc cc -c hello.c" or CC="distcc  gcc".
              This  is convenient when you want to use distcc for
              only some compilations or to try it  out,  but  can
              cause  trouble  with  some makefiles or versions of

       explicitly.


MASQUERADING

       The basic idea is to create a "masquerade directory" which
       contains links from the name of the real compiler  to  the
       distcc  binary.   This  directory is inserted early on the
       PATH, so that calls to the compiler  are  intercepted  and
       distcc  is  run  instead.  distcc then removes itself from
       the PATH to find the real compiler.

       For example:

              # mkdir /usr/lib/distcc/bin
              # cd /usr/lib/distcc/bin
              # ln -s ../../../bin/distcc gcc
              # ln -s ../../../bin/distcc cc
              # ln -s ../../../bin/distcc g++
              # ln -s ../../../bin/distcc c++

       Then, to use distcc, a user just needs to put  the  direc­
       tory /usr/lib/distcc/bin early in the PATH, and have set a
       host list in DISTCC_HOSTS or a file.  distcc  will  handle
       the rest.

       Note that this masquerade directory must occur on the PATH
       earlier than the directory that contains the  actual  com­
       pilers  of the same names, and that any auxiliary programs
       that these compilers call (such as as or ld) must also  be
       found  on  the  PATH  in  a directory after the masquerade
       directory since distcc calls out to the real compiler with
       a  PATH  value  that has all directory up to and including
       the masquerade directory trimmed off.

       It is possible to get a "recursion  error"  in  masquerade
       mode,  which  means  that distcc is somehow finding itself
       again, not the real compiler.  This can indicate that  you
       have  two  masquerade  directories  on  the PATH, possibly
       because of having two distcc  installations  in  different
       locations.  It can also indicate that you're trying to mix
       "masqueraded" and "explicit" operation.


USING DISTCC WITH CCACHE

       ccache is a program that speeds software builds by caching
       the  results  of  compilations.  ccache is normally called
       before distcc, so that results are retrieved from a normal
       cache.

       The  simplest  way  to use ccache with distcc is to create
       masquerade directories for both  of  them,  and  list  the
       ccache directory on the path before distcc.  For example:

              PATH=/usr/lib/ccache/bin:/usr/lib/distcc/bin:/usr/bin:/bin

       distcc emits a warning and compiles locally.

       The host list is a simple  whitespace  separated  list  of
       host specifications.  The simplest and most common form is
       a host names, such as

              localhost red green blue

       distcc prefers hosts towards the start  of  the  list,  so
       machines  should  be  listed in descending order of speed.
       In particular, when only a single compilation can  be  run
       (such  as  from  a  configure  script),  the first machine
       listed is used.  Because the overheads  for  running  jobs
       locally  are  low, localhost should normally be first.  If
       the  client  is  much  slower  (for  example,  a  handheld
       machine) then it can be listed later or not at all.

       The syntax is

         DISTCC_HOSTS = HOSTSPEC ...
         HOSTSPEC = LOCAL_HOST | SSH_HOST | TCP_HOST | OLDSTYLE_TCP_HOST
         LOCAL_HOST = localhost[/LIMIT]
         SSH_HOST = [USER]@HOSTID[/LIMIT][:COMMAND][OPTIONS]
         TCP_HOST = HOSTID[:PORT][/LIMIT][OPTIONS]
         OLDSTYLE_TCP_HOST = HOSTID[/LIMIT][:PORT][OPTIONS]
         HOSTID = HOSTNAME | IPV4
         OPTIONS = ,OPTION[OPTIONS]
         OPTION = lzo

       Here are some individual examples of the syntax:

       localhost
              The  literal  word  "localhost" is interpreted spe­
              cially to cause compilations to  be  directly  exe­
              cuted,  rather than passed to a daemon on the local
              machine.  If you do want to connect to a daemon  on
              the  local  machine  for  testing,  then  give  the
              machine's IP address or real hostname.  (This  will
              be slower.)

       IPV4   A literal IPv4 address, such as 10.0.0.1

       HOSTNAME
              A hostname to be looked up using the resolver.

       :PORT  Connect  to a specified decimal port number, rather
              than the default of 3632.

       @HOST  Connect to the host  over  SSH,  rather  than  TCP.
              Options  for  the  SSH  connection  can  be  set in
              ~/.ssh/config

              defaults  to  four  per  host,  but  may be further
              restricted by the server.  You should only need  to
              increase  this  for servers with more than two pro­
              cessors.

       ,lzo   Enables LZO compression for this TCP or SSH host.

       Here is an example demonstrating some possibilities:

              localhost/2   @bigman/16:/opt/bin/distccd    oldma­
              chine:4200/1 distant/3,lzo

       If  a host in the list is not reachable distcc will emit a
       warning and ignore that host for about one minute.


COMPRESSION

       The lzo host option specifies that LZO compression  should
       be  used for data transfer, including preprocessed source,
       object code and error messages.   Compression  is  usually
       economical  on  networks  slower than 100Mbps, but results
       may vary depending on the network, processors  and  source
       tree.

       Enabling  compression  makes  the distcc client and server
       use more CPU time, but less network traffic.  The compres­
       sion  ratio is typically 4:1 for source and 2:1 for object
       code.

       Using compression requires both client and server  to  use
       at  least  release 2.9 of distcc.  No server configuration
       is required: the server always  responds  with  compressed
       replies to compressed requests.


DIAGNOSTICS

       Error  messages or warnings from local or remote compilers
       are passed through to diagnostic output on the client.

       distcc can supply extensive debugging information when the
       verbose  option  is  used.   This  is  controlled  by  the
       DISTCC_VERBOSE environment variable on the client, and the
       --verbose  option  on  the  server.   For troubleshooting,
       examine both the client and server error messages.


EXIT CODES

       The exit code of distcc is normally that of the  compiler:
       zero for successful compilation and non-zero otherwise.

       distcc  distinguishes  between  "genuine" errors such as a
       syntax error in the source, and "accidental"  errors  such
       as a networking problem connecting to a volunteer.  In the
       case of accidental errors, distcc will retry  the  connec­
       tion  locally  unless  the DISTCC_FALLBACK option has been
       111    Recursive call to distcc.

       116    No hosts defined and fallbacks disabled.

       (Others are listed in exitcode.h.)


FILES

       If $DISTCC_HOSTS is not set, distcc reads a host list from
       either ~/.distcc/hosts or a system-wide configuration file
       set at compile time.  The file locations are shown in  the
       output from distcc --help

       distcc creates a number of temporary and lock files under­
       neath the temporary directory.


ENVIRONMENT VARIABLES

       distcc's behaviour is controlled by a number  of  environ­
       ment variables.  For most cases nothing need be set if the
       host list is stored in a file.

       DISTCC_HOSTS
              Space-separated list of volunteer  host  specifica­
              tions.

       DISTCC_VERBOSE
              If  set  to 1, distcc produces explanatory messages
              on the standard error stream or in  the  log  file.
              This  can  be  helpful  in debugging problems.  Bug
              reports should include verbose output.

       DISTCC_LOG
              Log file to receive messages  from  distcc  itself,
              rather than stderr.

       DISTCC_FALLBACK
              By  default distcc will compile locally if it fails
              to distribute a job to the indended machine, or  if
              not  host  list  can be found.  If this variable is
              set to 0 then fallbacks are disabled and those com­
              pilations  will  simply  fail.  Note that this does
              not affect jobs which must always be local such  as
              linking.

       DISTCC_SAVE_TEMPS
              If  set to 1, temporary files are not deleted after
              use.  Good for debugging, or if your disks are  too
              empty.

       DISTCC_TCP_CORK
              If  set  to  0, disable use of "TCP corks", even if
              they're present on this system.  Using  corks  nor­
              mally  helps  pack  requests into fewer packets and
              /tmp/ is used.

       UNCACHED_ERR_FD
              If  set and if DISTCC_LOG is not set, distcc errors
              are written to the file  descriptor  identified  by
              this  variable.   This  is intended mainly to allow
              transient errors such as network  errors  to  avoid
              being cached by ccache.


CROSS COMPILING

       Cross  compilation  means  building  programs  to run on a
       machine with a different processor, architecture, or oper­
       ating system to where they were compiled.  distcc supports
       cross compilation, including teams  of  mixed-architecture
       machines,  although  some  changes to the compilation com­
       mands may be required.

       The compilation command passed to distcc must be one  that
       will  execute  properly on every volunteer machine to pro­
       duce an object file  of  the  appropriate  type.   If  the
       machines  have  different  processors,  then  simply using
       distcc cc will probably not work, because that  will  nor­
       mally invoke the volunteer's native compiler.

       Machines with the same CPU but different operating systems
       may not necessarily generate compatible .o files.

       Several different  gcc  configurations  can  be  installed
       side-by-side  on  any  machine.   If  you  build  gcc from
       source, you should use the --program-suffix  configuration
       options  to  cause  it  to  be  installed with a name that
       encodes the gcc version and the target platform.

       The recommended convention for the gcc name is TARGET-gcc-
       VERSION such as i686-linux-gcc-3.2 .  GCC 3.3 will install
       itself under this name, in addition to TARGET-gcc and,  if
       it's native, gcc-VERSION and gcc .

       The  compiler must be installed under the same name on the
       client and on every volunteer machine.


BUGS

       If you think you have found a  distcc bug, please see  the
       file reporting-bugs.txt in the documentation directory for
       information on how to report it.

       Due to limitations in gcc, gdb may not be able to automat­
       ically  find  the  source  files  for programs built using
       distcc in some circumstances.  The gdb  directory  command
       can be used.

       gcc's -MD option can produce output in the wrong directory
       have  changed  over  time,  and  some  distributors   have
       included incompatible patches without changing the version
       number.  distcc does not protect against using  incompati­
       ble versions.

       Some  makefiles  have  missing  or extra dependencies that
       cause incorrect or slow parallel builds.  Fix the makefile
       by  correcting  the dependencies, report bugs to the main­
       tainer, or don't build the tree in parallel.

       Other    known    bugs    may     be     documented     on
       http://distcc.samba.org/


AUTHOR

       distcc  was  written  by Martin Pool <mbp@sourcefrog.net>,
       with the co-operation of  many  scholars  including  Wayne
       Davison,  Frerich  Raabe,  Dimitri Papadopoulos and others
       noted  in  the  NEWS  file.    Please   report   bugs   to
       <distcc@lists.samba.org>.


LICENCE

       You are free to use distcc.  It may be copied, modified or
       distributed only under the terms of the GNU General Public
       Licence version 2 or later.  A copy of the GPL is included
       in the file COPYING.


SEE ALSO

       distccd(1),       ccache(1),        gcc(1),        make(1)
       http://distcc.samba.org/ http://ccache.samba.org/

                           21 July 2003                 distcc(1)
  
Help us cut cost by not downloading the whole site!
Use of automated download sofware ("harvesters") such as wget, httrack, etc. causes the site to quickly exceed its bandwidth limitation and therefore is expressedly prohibited. For more details on this, take a look here

Login
Nickname

Password

Security Code
Security Code
Type Security Code


Don't have an account yet? You can create one. As a registered user you have some advantages like theme manager, comments configuration and post comments with your name.

Help if you can!


Amazon Wish List

Did You Know?
You can choose larger fonts by selecting a different themes.


Friends



Tell a Friend About Us

Bookmark and Share



Web site powered by PHP-Nuke

Is this information useful? At the very least you can help by spreading the word to your favorite newsgroups, mailing lists and forums.
All logos and trademarks in this site are property of their respective owner. The comments are property of their posters. Articles are the property of their respective owners. Unless otherwise stated in the body of the article, article content (C) 1994-2013 by James Mohr. All rights reserved. The stylized page/paper, as well as the terms "The Linux Tutorial", "The Linux Server Tutorial", "The Linux Knowledge Base and Tutorial" and "The place where you learn Linux" are service marks of James Mohr. All rights reserved.
The Linux Knowledge Base and Tutorial may contain links to sites on the Internet, which are owned and operated by third parties. The Linux Tutorial is not responsible for the content of any such third-party site. By viewing/utilizing this web site, you have agreed to our disclaimer, terms of use and privacy policy. Use of automated download software ("harvesters") such as wget, httrack, etc. causes the site to quickly exceed its bandwidth limitation and are therefore expressly prohibited. For more details on this, take a look here

PHP-Nuke Copyright © 2004 by Francisco Burzi. This is free software, and you may redistribute it under the GPL. PHP-Nuke comes with absolutely no warranty, for details, see the license.
Page Generation: 0.13 Seconds