How to embed scconfig in your project
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. getting the files in place

 This is the first step. Any later step will assume you did this step
 exactly as described in section 1.1 or in section 1.2.

 1.1. with svn external
  Normally your project will have a subdirectory called scconfig/ and
  all scconfig files would be there. If your project is hosted in svn,
  the easiest way to do this is adding an svn external:
    cd myproject/trunk
    svn mkdir scconfig
    svn propset svn:externals scconfig/src svn://svn.repo.hu/scconfig/trunk/src
    svn propset svn:externals scconfig/doc svn://svn.repo.hu/scconfig/trunk/doc
    svn propset svn:externals scconfig/examples svn://svn.repo.hu/scconfig/trunk/examples

  The advantage of this method is that scconfig updates will automatically
  fetched upon svn up in your project. If you do not like this, and want
  to freeze scconfig, you still can make a copy as described section in 1.2.

 1.2. without svn
  If your project is not version controlled by svn, you should copy trunk/
  from scconfig to be a directory called scconfig/ in your project tree.

2. configuring scconfig for your project
 Scconfig is generic and contains a lot of tests. Most projects will need only
 a small fraction of all tests. This section is dealing with customizing
 scconfig to do exactly what needs to be done in your project.

 2.1. Copying Makefile
  Copy scconfig/examples/Makefile to scconfig/Makefile and edit the
  configuration part. If you do not need any of the tests from a plugin,
  just comment the line that includes the Makefile.plugin of that plugin.
  If you did 1.2. you can also delete the corresponding plugin directory
  to save disk space.

 2.2. Copying hooks.c
  Copy scconfig/examples/hooks.c to scconfig/hooks.c and edit it. The
  original file will run all available tests, which is probably not what
  you want. Remove lines "require_all()" and add require() lines to those
  nodes you will need when generating your Makefiles and other outputs.
  Such a require line looks like:
    require("cc/cc", 0, 1);
  where "cc/cc" is the node name (note: you shouldn't use "/target/" or
  "/host/" prefix here), 0 is the log level (indentation) and 1 means
  if the test fails, that's a fatal condition and configure should stop.
  Place 0 there if failing to detect the feature is not fatal.
  For more info on available nodes, refer to doc/tree.txt.

  The hook calls returning int should return zero on success - any other
  return value causes scconfig to stop. This feature is for those who
  do not like to abort() or exit(), a clean way of failure is provided.

  Please note that you can hardly enforce order of tests: if you require()
  something and it depends on other things, those dependencies will be
  resolved first and if you have require() lines for them later, nothing
  will happen there since nothing will be checked twice.

  It is essential to fill in hook_detect_target() - this is the function
  that actually orders scconfig to do tests. For more info on host/target
  approach, please read doc/host_target.txt.

  Function hook_generate() is the other thing you should fill in: this
  is the place where file generation should happen, which is the reason
  for running scconfig in the first place. You have multiple options here:
   A. write your own C code that writes the output files using fprintf()
      for example. In this case you can access nodes by get().
   B. use the provided template generator plugin and write templates
      for your output files. In this case the C code will contain only
      calls to the generator with input/output file name pairs. For
      more information, refer to generator.html.
   C. you can even combine the above two strategies and generate "simple"
      files with the generator plugin and do the "complex" files by C
      code.

3. ./configure
 If you are done with all that, you should have a scconfig/configure after
 a make in scconfig/. To make it more smooth for the user, you should provide
 a small shell script in your project dir (parent of scconfig). The
 script should be called configure, with a content similar to this:
  #!/bin/sh
  cd scconfig
  make
  ./configure $*