RearrangedHeaders < FC3upgrade

FC3upgrade Web>RearrangedHeaders (22 Aug 2005, AlastairScobie) (raw view)EditAttach
---+ FC3 LCFG Header File Structure

For FC3 we have rearranged the LCFG header file structure. There are many reasons for wanting to do this, not least:

   * To separate the headers into layers much like the package structure was separated for RH9.
   * To make refactoring and overall organisation simpler.
   * To improve the cohesion and containment of groups of resources, i.e. things that are related should be kept togther and things that are not should be kept apart.


---++Table of Contents:

   * [[#HowChanged][How Profiles Have Changed, In Practice..]]
   * [[#OrgOfSource][Organisation of LCFG Header Source Files]]
   * [[#SearchPaths][Header and Package Search Paths On The LCFG Servers]]
  

#HowChanged
---++ How Profiles Have Changed, In Practice..

<table border="1">
<th>Old Machine Profile</th><th>New Machine Profile</th>
<tr>
<td valign="top">
<verbatim>
/* gala */

#include <lcfg/os/redhat9.h>
#include <lcfg/hwbase/hp_d530.h>
#include <inf/sitedefs.h>
#include <inf/office-jcmb.h>
#include <inf/wire_c.h>

dhclient.mac   00:11:85:F3:1D:3D

inv.sno        FRB4480GDR
inv.location   JCMB-2422
inv.allocated  ascobie
</verbatim>
</td>
<td valign="top">
<verbatim>
/* gala */

#include <dice/os/fc3.h>
#include <dice/hw/hp_d530.h>
#include <dice/options/office-kb.h>
#include <live/wire_c.h>


dhclient.mac   00:11:85:F3:1D:3D

inv.sno        FRB4480GDR
inv.location   JCMB-2422
inv.allocated  ascobie
</verbatim>
</td>
</tr></table>


---+++ Important Notes About New Machine Profiles

   * Note that no lcfg level headers are referenced, only dice level (and live). The layers upon which dice sits (ed and lcfg) are now hidden from view.
   * The live level headers should always come last. They should *never* come before a dice level header.
   * There is no longer any segregation of hardware and software options; they both now live together in =options=.
   * The vast majority of desktop machines should include one of:<blockquote>
      * =#include &lt;dice/options/studentlabs-at.h&gt;=
      * =#include &lt;dice/options/studentlabs-bp.h&gt;=
      * =#include &lt;dice/options/studentlabs-fh.h&gt;=
      * =#include &lt;dice/options/studentlabs-kb.h&gt;=
      * =#include &lt;dice/options/office-at.h&gt;=
      * =#include &lt;dice/options/office-bp.h&gt;=
      * =#include &lt;dice/options/office-fh.h&gt;=
      * =#include &lt;dice/options/office-kb.h&gt;=
</blockquote>
   * =inv.manager= is set to =support-team= in the above headers - it should only be
     overriden where the machine's manager is not the support-team
   * =inv.allocated= is set to =teachinglab= in the studentlabs headers - it should not need
     to be overriden.
   * =inv.owner= is set to =informatics= by default to indicate that the machine was purchased 
     off core school funds. It should be set to the relevant institute (eg LFCS, CISA etc)
     if the machine was bought off research funds.


#OrgOfSource
---++ Organisation of LCFG Header Source Files

To best understand what is commented upon in the following sections you should probably checkout a working copy of the current header files first by following the instructions on the SubversionRepository page.

It may also be useful to open a copy of this high level [[%ATTACHURL%/lcfg_structure.png][LCFG Header Structure Diagram]] in a separate web browser window (right clicking on the link in most browsers will give you the option to open in a new tab or window). The diagram
shows the relationships between the various levels and files described in the sections that follow.

The LCFG header files and package lists are split into the following levels for FC3:

   * [[#LCFGLevel][LCFG Level]]
   * [[#EDLevel][Ed Level]]
   * [[#DICELevel][DICE Level]]

Note that the =README= file in the LCFG Subverison module root gives a quick overview of the directory strucures within the module. It is best used in conjunction with this guide.


#LcfgLevel
---+++ LCFG Level (lcfg)

This is the global LCFG level. Any resources in these files must be applicable to _any_ LCFG
installation.

<!-- Do these clutter up the rendered page too much? - cedward1
---++++ LCFG Header Files
-->

   $ =core/include/lcfg/defaults.h=: This is the core LCFG defaults header, for all platforms. It includes the individual compenent default resources from the following directory, but only for those components which are considered part of the _base_ platform.
   $ =core/include/lcfg/defaults/&lt;component&gt;.h=: This directory contains a file per LCFG level component, containing the default resources for that component.
   $ =core/include/lcfg/hw/&lt;model&gt;.h=: This directory contains a file per LCFG level machine model.
   $ =core/include/lcfg/options/&lt;option&gt;.h=: This directory contains a file per LCFG level software or hardware option. 

Operating system dependent resources are selected using the following CPP definitions:

   * =#define OS_LINUX=
   * =#define LINUX_FC3=
   * =#define LINUX_RH9=

   * =#define OS_SOLARIS=
   * =#define SOLARIS_8=
   * =#define SOLARIS_9=

-- Main.CarwynEdwards: Maybe the OS selection stuff should live in its own section?

<!--
---++++ LCFG Package Lists
-->

   $ =core/packages/lcfg= : This directory contains package lists for the LCFG level.


#EdLevel
---+++ ED Level (ed)

This is the Edinburgh University wide level. Any resources in these files must be appropriate
to any school in the University. Note that this level should not be considered as a fully fleshed ED LCFG deployment - it is a class of LCFG which can be inherited by individual school LCFG deployments. 

<!--
---++++ ED Header Files
-->

   $ =core/include/ed/defaults.h=: This file includes the LCFG level =defaults.h=, additionally sets any ED level specific resources and includes any additional components that are required for the ED level base platform.
   $ =core/include/ed/defaults/&lt;component&gt;.h=: This directory contains a file per ED level component, containing the default resources for that component.
   $ =core/include/ed/hw/&lt;model&gt;.h=: This directory contains a file per ED level machine model. These files may include the matching LCFG level machine model header, if it exists, and perhaps set some ED level specific resources for that model.
   $ =core/include/ed/options/&lt;option&gt;.h=: This directory contains a file per ED level software or hardware option. As with the above directory, these files may include the matching LCFG level option header, if it exists.

<!--
---++++ ED Package Lists
-->

   $ =core/packages/ed=: This directory contains package lists for the ED level.


#DiceLevel
---+++ DICE Level (dice)

This is the DICE level. 

<!--
---++++ DICE Header Files
-->

   $ =core/include/dice/defaults.h=: This file includes the ED level =defaults.h=, additionally sets any DICE level resources and includes any additional components that are required for the DICE level base platform.
   $ =core/include/dice/defaults/&lt;component&gt;.h=: This directory contains a file per DICE level component, containing the default resources for that component.
   $ =core/include/dice/hw/&lt;model&gt;.h=: This directory contains a file per DICE level machine model. These files may include the matching ED or LCFG level machine model header, if one exists, and perhaps set some DICE level specific resources for that model.
   $ =core/include/dice/options/&lt;option&gt;.h=: This directory contains a file per DICE level software or hardware option. As with the above directory, these files may include the matching ED or LCFG level option header, if one exists.
   $ =core/include/dice/os/&lt;os&gt;.h=: This directory contains a header per operating system; each header merely setting the appropriate OS CPP variable and including the DICE level defaults.h header.

<!--
---++++ DICE Package Lists
-->

   $ =core/packages/dice=: This directory contains package lists for the DICE level.


#SearchPaths
---++ Header and Package Search Paths On The LCFG Servers

The following paths from the structures described above are included in the search paths used by the LCFG Server:

   $ =server.hdrpath=: This is the search path for LCFG header (=*.h=) files:
      * =core/include=
   $ =server.pkgpath=: This is the search path for LCFG package lists (=*.rpms=, =*.pkgs=):
      * =core/packages/dice=
      * =core/packages/ed=
      * =core/packages/lcfg=


---++ Footnotes and Authors

It may be a good idea to mention coding standards in the context of this document. The areas relevent to LCFG souces would seem to be:

   * Comments (how and when).
   * File naming conventions (underscores vs dashes in particular - there is already inconsistency).
   * Conventions to use when using CPP conditionals.
   * Header file organisation.

References:

   * http://cm.bell-labs.com/cm/cs/cbook/
   * http://www.doc.ic.ac.uk/lab/secondyear/cstyle/cstyle.html
   * http://www.chris-lott.org/resources/cstyle/

-- Main.CarwynEdwards - 21 Jun 2005

-- Main.AlastairScobie - 21 Jun 2005
Attachments
Topic attachments
I	Attachment	Action	Size	Date	Who	Comment
png	lcfg_structure.png	manage	64.7 K	22 Jun 2005 - 02:04	CarwynEdwards	LCFG Header Structure Diagram
Topic revision: r20 - 22 Aug 2005 - 23:39:05 - AlastairScobie
FC3upgrade
FC3upgrade Web
FC3upgrade Web Home
Changes
Index
Search
My links
My home page
edit
Copyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
This Wiki uses Cookies