Changeset 752

Timestamp:

08/09/07 22:40:06 (1 year ago)

Author:

Gregor

Message:

docs/README.software_engineers: Many improvements thanks to suggestions by Bill Baxter.

Files:

• trunk/docs/README.software_engineers (modified) (8 diffs)

trunk/docs/README.software_engineers

@@ -1 +1 @@
-= DSSS Documentation for Software Engineers =
-
-
+, the D Shared Software System,
-
-* Build D software.
@@ -42 +42 @@
-
-A section is started with the file name of the source module or package in
-
-
-
+
+
+
+
+
+
+
+
+
+
-
-= SETTINGS =
@@ -65 +72 @@
-described later.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
-
-DSSS provides several environment variables for this purpose:
@@ -167 +83 @@
-ETC_PREFIX: The prefix for configuration files.
-EXE_EXT: The extension for executable files. Empty on POSIX, ".exe" on Windows.
+DSSS: The full path to the DSSS binary itself.
+DSSS_BUILD: The full path to the build tool being used by DSSS (usually
+            rebuild).
+
+= FLAGS =
+
+Any section may have a 'buildflags' setting, which specifies the flags to be
+used while building that section. For example,
+buildflags=-O
+
+= SECTION TYPES =
+
+Although section types are usually determined automatically from the section
+name, they may also be overridden with the 'type' setting:
+[oneFileLib.d]
+type=library
+
+The valid values for 'type' (all described in later sections) are:
+binary
+library
+sourcelibrary
+special
+subdir
+
+= BINARIES =
+
+Sections which are named for D modules (.d files) produce executable binaries
+when built with DSSS. The target binary file name will be deduced from the name
+of the .d file, or can be set explicitly with a 'target' line, such as:
+[example.d]
+target=example_binary
+
+Windows users: Be careful not to set the target of a binary build to the name of
+a directory. This will work on Windows because it gains the .exe suffix, but
+will fail on other operating systems.
+
+= LIBRARIES =
+
+Sections which are named for D packages (directories) produce libraries when
+built with DSSS. The name of the library file is derived from the name of the
+package and the platform. There is no reason to remember this name, however,
+because DSSS will detect library dependencies and link them in automatically.
+This name can partially be overridden if desired, in the same way as binaries:
+[mydpackage]
+target=dlibrary
+
+However, the platform will always affect the output library name. On POSIX
+systems, the above library will be named libSdlibrary.a and libdlibrary.so. On
+Windows, the above library will be named Sdlibrary.lib.
+
+By default, all of the .d files within the directory and any subdirectory will
+be included in the library. Files may be excluded with the 'exclude' setting:
+[mydpackage]
+exclude=mydpackage/broken.d
+
+Entire directories may also be excluded:
+[mydpackage]
+exclude=mydpackage/brokenpackage
+
+The 'exclude' setting is useful in concert with versioning, described in a later
+section.
+
+= SOURCE LIBRARIES =
+
+Source libraries are libraries which are not compiled until they are used in a
+binary. They are installed in their source form. Otherwise, they act identically
+to normal libraries. A source library may be specified by setting the 'type'
+setting to 'sourcelibrary':
+[mydpackage]
+type=sourcelibrary
+
+= SPECIAL SECTIONS =
+
+It is also possible to create sections which are not associated with compiling
+a binary or library. These sections are given names starting with a '+', such
+as:
+[+generate]
+
+The utility of these sections will be seen below, in the section on hooks.
+
+
+== INSTALLATION ==
+
+DSSS is capable of installing binaries and libraries to a predetermined
+directory, usually the prefix in which it is installed. When libraries are
+installed in this way, they will be usable by DSSS without being explicitly
+specified.
+
+
+== DEPENDENCIES ==
+
+The primary reason that DSSS exists is to make handling dependencies easier. To
+this end, is is never necessary to explicitly specify a dependency upon a
+library which is itself set up to use DSSS. Because DSSS traces D imports and
+keeps an Internet-accessible repository of package information, installing the
+dependencies which are supported by DSSS is as easy as typing:
+$ dsss net deps
+
+However, dependencies on non-DSSS D libraries or C libraries can be more
+complicated.
+
+= INCLUDE PATHS =
+
+It is possible to specify include paths in the 'buildflags' settings. Import
+paths are specified with the -I flag:
+buildflags=-I../prerequisite/import
+
+= PREREQUISITE LIBRARIES =
+
+Library search paths are specified with the -S flag:
+buildflags=-S../prerequisite/lib
+
+Libraries can be explicitly linked in with the -ll flag. -ll works similarly to
+-l in most compilers. On POSIX and similar platforms, a flag such as
+-ll<library>
+will link in a library named
+lib<library>.a (or lib<library>.so)
+
+On Windows (except GDC), the same flag will link a library named
+<library>.lib
+
+Libraries linked in with the -ll flag are searched for in the search paths
+specified by the -S flag.
+
+The -ll flag is only useful for explicitly linking libraries into binaries. If
+your library depends on a non-DSSS library, you must list that dependency in a
+.d file which is part of your library. This is done with the 'link' pragma,
+which must always be specified within version(build):
+version (build) {
+    pragma(link, "example");
+}
+
+The above example will cause any binary linked against your library to link
+against the library named libexample.a (or example.lib on Windows).
+
+
+== HOOKS ==
+
+DSSS can run arbitrary commands while building software. There are a number of
+points at which commands can be run: before and after building, before and after
+installing, and before and after cleaning up. These commands are added to
+'prebuild', 'postbuild', 'preinstall', 'postinstall', 'preclean' and 'postclean'
+lines, respectively.
+
+Hook commands can be anything which can be run on the shell of the host system,
+such as:
+prebuild = echo Hello
+
+Any number of hook commands may be strung together between semicolons:
+prebuild = echo Hello ; echo World
+
+And may span multiple lines by ending each line with a backslash:
+prebuild = echo \
+    Hello ; \
+    echo World
+
-
-
@@ -186 +258 @@
-prebuild = cd c_source ; make
-
+You do not need to return to the original directory after 'cd'ing. The
+directory will be restored after the hook commands have finished.
+
-= .d files =
-
@@ -193 +268 @@
-= set =
-
-setting in the dsss.conf file on-the-fly. The
-parameters 
+dsss.conf file setting while building. The parameters
+
-set <section>:<setting> <value>
-
@@ -207 +282 @@
-set example.d:postbuild echo Hello
-
-
-
+
+
+
+
-
-= add =
@@ -282 +359 @@
-
-
+== ADVANCED FEATURES ==
+
+There are several advanced features of DSSS which do not need any modification
+to the dsss.conf file to use.
+
+The flag '--test', when passed to `dsss build`:
+$ dsss build --test
+will cause all of the unit tests to be run.
+
+The flag '--doc', when passed to `dsss build`:
+$ dsss build --doc
+will cause API documentation for every library to be generated with CandyDoc,
+which beautifies and organizes the documentation.
+
+
-To-be-written:
-== SUBDIRECTORIES ==
-INTERNAL OPER
+NET INSTALL
-
-