Changeset 758

Timestamp:

08/12/07 03:16:51 (1 year ago)

Author:

Gregor

Message:

docs/README.software_engineers: Added information on the 'shared' option.

Files:

• trunk/docs/ChangeLog (modified) (1 diff)
• trunk/docs/README.software_engineers (modified) (3 diffs)

trunk/docs/ChangeLog

@@ -1 +1 @@
-SVN from 0.70:
+        - Much-improved README.software_engineers.
-        - Fixed 'set' and 'add' commands (see ticket #102).
-        - Added 'error' and 'warn' hook commands (see ticket #103).

trunk/docs/README.software_engineers

@@ -71 +71 @@
-The setting 'a' is now 'Hello World'. This is most useful with versioning,
-described later.
+
+Some settings do not require values. In this case, the setting name alone is
+sufficient, such as:
+shared
-
-Settings may include references to environment variables:
@@ -145 +149 @@
-section.
-
+When using GDC on GNU/Linux, it is also possible to build shared libraries (.so
+files). To specify that a shared library should be built, set the 'shared'
+option in the library's section:
+[mydpackage]
+shared
+
+You can set the .so file's version extension (the 1.2.3 in .so.1.2.3) with the
+soversion setting:
+[mydpackage]
+shared
+soversion=3.2.1
+
-= SOURCE LIBRARIES =
-
@@ -401 +417 @@
-== SUBDIRECTORIES ==
-== NET INSTALLATION ==
-
-
--put this somewhere-
-When a library is installed via DSSS, the .d files are translated into .di (D
-import) files, which are then installed to /include/d with the appropriate
-names. These D import files contain references to the library itself, which
-allows DSSS to include it when necessary without the user specifying it.
-
-
-
-== OLD CONTENT (please ignore) ==
-
-DSSS is a tool to:
-
-* Build D software.
-* Install D software.
-* Configure D software dependencies and libraries.
-* Maintain a repository of DSSS-compatible D sources to be easily installable
-  via the Internet.
-
-To the average software engineer, the most important part is dsss.conf, the
-file added to your source code to configure how DSSS will compile it.
-
-dsss.conf is a plain-text file, with a similar syntax to Windows INI files. It
-can have any number of sections, each of which is headed with a name in
-brackets, like so:
-[foo/bar.d]
-
-
-Most sections are named by a source file or directory. In general, sections
-named for source files will generate binaries, and sections named for
-directories will generate libraries. However, you can manually specify a
-binary, library or sourcelibrary (like a library, but not compiled until it's
-used in a binary) with the type setting:
-[wholedirbinary]
-type=binary
-
-[onefilelibrary.d]
-type=library
-
-[onefilesrclib.d]
-type=sourcelibrary
-
-
-In each section, there can be any number of settings. Each setting is a
-keyword, possibly followed by = or += and a value. For example, the "target"
-setting sets the name of the output binary or library in a given section:
-[main.d]
-target=dzip
-
-(In general, the target setting will be automatically set to something
-sensible)
-
-
-Sections creating libraries from directories will normally include all the .d
-files in that directory or any subdirectory of it. It is also possible to
-specify subdirectories explicitly in dsss.conf, which will cause some .d files
-to be reassigned. For example, if you have these files:
-dzip/algorithm.d, foo/compression/zip.d
-and a section:
-[dzip]
-then the produced library will include algorithm.d and zip.d.
-If you have two sections:
-[dzip]
-[dzip/compression]
-then two libraries will be produced: The library from 'dzip' will contain
-algorithm.d, and the library from [dzip/compression] will contain zip.d.
-
-
-Furthermore, content in dsss.conf can be set up as version-specific, with a
-version keyword similar to the version keyword in D. For example, to make sure
-that a certain binary is only produced on Windows:
-version (Windows) {
- [dzip/windows.d]
- target=dzip_for_windows
-}
-
-The version keyword in dsss.conf also supports negation:
-version (!Windows) {
- [dzip/nonwindows.d]
- target=dzip_for_nonwindows
-}
-
-The version statement also supports an 'else' clause:
-version (Windows) {
- [foo/windows.d]
- target=foo_for_windows
-} else {
- [foo/notwindows.d]
- target=foo_for_notwindows
-}
-
-The version statement in dsss.conf has a fairly strict syntax: the { must be on
-the same line as the statement, and the version being tested must be in
-parenthesis.
-
-
-There are quite a few other settings supported:
-
-* exclude
-  * Exclude a list of .d files from being included in a library:
-    exclude=foo.d bar.d
-
-* buildflags
-  * Flags that will be added to the command line for rebuild when building this
-    section.
-
-* prebuild, preinstall, preclean, predigen, postbuild, postinstall, postclean,
-  postdigen
-  * Commands to be run before or after (pre or post) building (build),
-    installing (install), cleaning (clean) or generating .di files (digen) for
-    the current section. Can be any number of ;-separated commands, and
-    supports some special command types:
-    * .d files. If a .d file is specified as a command, it will be compiled and
-      run.
-      * Notably, D files can always use DSSS' headers. That is, the package
-        'sss'.
-
-    * install: DSSS has an internal 'install' command, which takes the
-      following syntax:
-      install <file> <target directory>
-
-    * eval: Run a command (.d file or otherwise), and execute its result
-      * For example, the command could print "install chosen/file/to/install
-        $INCLUDE_PREFIX"
-
-    * set: Set a setting in DSSS' environment. The syntax is as follows:
-      * set <section>.<setting> <value>
-      * You may use * to apply a setting to all sections, or simply exclude the
-        section (but still include the .) to set a global setting.
-      * This is most useful when used via eval, as in:
-        eval detectsettings.d
-
-    * add: Like set, but adds to a setting.
-
-  * In any command, you can use environment variables with a '$', such as
-    $PREFIX. The following environment variables are provided by DSSS:
-    * $DSSS : The dsss binary, if you need to call DSSS recursively. Better
-      than counting on it being on the PATH.
-
-    * $PREFIX : The prefix to which the software is being installed.
-
-    * $BIN_PREFIX : The prefix to which binaries are being installed.
-
-    * $LIB_PREFIX : The prefix to which libraries are being installed.
-
-    * $INCLUDE_PREFIX : The prefix to which generated .di interface files are
-      being installed.
-      * This is the /base/ prefix, so for example the module foo.bar will be
-        installed to $INCLUDE_PREFIX/foo/bar.di
-      * This directory can also be used for .d files.
-
-    * $DOC_PREFIX : The prefix to which documentation is installed.
-
-    * $ETC_PREFIX : The prefix to which configuration files are being
-      installed.
-
-
-Furthermore, there is a global section for settings which are not specific to
-any binary or library. You can add settings to this section simply by adding
-them before any section declarations, or by making an empty section declaration
-like so:
-[]
-global_setting=0
-
-The important global settings are 'name' (which will otherwise be gleaned from
-the directory name) and 'version' (which will otherwise be set to 'latest').
-With these settings, a dsss.conf file would conventionally look something like
-this:
-name = dzip
-version = 1.0
-[dzip.d]
-target = dzip
-
-
-There is also a global setting, "requires", which may be used to explicitly
-list dependencies:
-requires = bintod
-In general, it is NOT necessary to use this setting, as DSSS will detect
-dependencies based on what is imported from the D source.
-
-
-It is possible to add a setting to all sections with the special [*] section:
-name = dzip
-version = 1.0
-[*]
-buildflags=-g
-[main.d]
-target = dzipper
-[dzip]
-
-
-You can make 'special' build steps, which do not correspond to D source files
-and so do not call the build tool, by naming them prefixed with a +. For
-example:
-[+genSource]
-prebuild = gensource.d
-
-
-It is possible to have source files spread out through several directories, and
-to support this in dsss.conf there is the special type "subdir":
-[subtool]
-type = subdir
-
-Each subdirectory must have its own dsss.conf . Note that setting type=subdir
-will cause DSSS to recurse into that directory, but will not cause that
-directory to be visible at compile time. If you want that feature, you will
-need to add -I flags to buildflags:
-name = dzip
-version = 1.0
-[*]
-buildflags=-g -Isubtool
-[subtool]
-type = subdir
-[main.d]
-target = dzipper
-[dzip]
-
-
-At build time, sections will be handled in the order that they appear in the
-dsss.conf file, with the exception that binaries are always built last. By
-default, every section will be built. This can be overridden with the global
-option 'defaulttargets', which allows you to specify a list of targets to build
-by default. All targets will be built if 'all' is explicitly specified on the
-command line.