DomTool/UserGuide

Domtool promotes code re-use using standard techniques from general programming. You can define shortcuts in one file in your ~/.domtool directory that you can then use from several other files. When you run domtool with no arguments, it checks which of your files mention shortcuts defined in other files, and it processes your files in the right order for this to work out right.

For instance, say that your home machine has IP address 1.2.3.4. Maybe you find yourself creating many different DNS mappings to that IP address. You could put this code in ~/.domtool/lib.dtl:

val homeIP = \host -> dnsIP host "1.2.3.4";

Then you could use your shortcut (called a "function" in Domtool and standard programming terminology) in another file in ~/.domtool:

dom "mydomain" with
  homeIP "home1";
  homeIP "home2"
end

You could also put the definition of homeIP in the same file as the use, at some point before that use but not inside any dom directive.

You can go further and create a factory for easy churning out of domains with similar configuration. Let's say that you have several domains that differ only in which directory you use to house the web pages for each one. Write this into ~/.domtool/lib.dtl:

val myDom = \name -> dom name where
  CreateWWW = false
with
  homeIP "myhouse";

  web "www" where
    ServerAdmin = "me@gmail.com"
  with
    serverAliasDefault;
    alias "/special" (home "shared_special_directory")
  end
end;

Now you can use your new directive like:

myDom "mydomain" where
  DocumentRoot = home "public_html/mydomain"
end

Besides all the standard stuff that dom sets up, myDom has given mydomain a DNS mapping from myhouse.mydomain to 1.2.3.4 and a mapping from http://www.mydomain/special/ to ~/public_html/mydomain, a shared directory where you might be storing a standard set of icons or other content you want to reuse across domains. The DocumentRoot you set in the use of myDom is automatically used by the web directive, because it sets an environment variable.

You can go even further and write your own directives that takes blocks of configuration as arguments, and then plug them into the resulting configuration in the right places. Here's an expanded version of myDom that lets you specify custom configuration for the domain overall:

val myDom = \name -> \\for_domain : Domain -> dom name where
  CreateWWW = false
with
  homeIP "myhouse";

  web "www" where
    ServerAdmin = "me@gmail.com"
  with
    serverAliasDefault;
    alias "/special" (home "shared_special_directory")
  end;

  for_domain
end;

Now you can use the new directive with a domain-specific DNS mapping:

myDom "mydomain" where
  DocumentRoot = home "public_html/mydomain"
with
  dnsIP "custom" "4.3.2.1"
end

In fact, the dom directive is implemented in more or less the same way in ~domtool/lib/easy_domain.dtl.

You might also want to make some standard environment variable settings that will persist across your different configuration files. For instance, to make FastCGI based PHP version 5 the default for all of your domains, put this in lib.dtl:

PhpVersion = php56;

Now this will be the default environment variable setting in all of your domains. While domtool does dependency analysis to find the right order for running files that use functions defined in other files with val, it doesn't do this for environment variable settings, which is why it's important to put default environment variable settings in lib.dtl. The dependency orderer has a special case for files with this name, always putting them first.

One final request about this subject: if you come up with function definitions that you think would be useful to other members, post about them on the hcoop-help mailing list, and we may add them to our standard library with your permission.

Giving Your Fingers a Break