"Fossies" - the Fresh Open Source Software archive

Member "linuxconf-1.35r1/doc/devguide.sgml" of archive linuxconf-1.35r1.src.tar.gz:

<!doctype linuxdoc system>
<article>
<title>Developers guide
<author>Introduction

<abstract>
	Linuxconf is a somewhat large project and like all software project,
	it takes some time to get comfortable with the source environment.
	This document tries to cover many conventions and trickeries used
	to develop Linuxconf.
</abstract>

<sect>Using make
<p>
	Here are various things to know about the make command and the Linuxconf
	project.


<sect1>Common targets
<p>
	There are few make targets that works everywhere in the source
	tree. They do the right thing (potentially nothing) in all
	sub-directory. This means that you are not force to launch make
	from the top level directory all the time. Here they are anyway

	<descrip>
	<tag/make without argument/

		It "compiles" what have to be compiled.
		If you are in a directory containing help files, it will
		transform the SGML files into HTML and help files. If you are
		in a source sub-directory, it will compile the .cc files. It will
		also link whatever utilities in that directory if needed.

	<tag/make install/

		will install whatever have to be installed. In
		many directory, this is a no op. Note that when you develop
		Linuxconf, you do not want to reinstall from scratch each time
		you want to test. You generally go in the main sub-directory, run
		"make" without argument to link Linuxconf, and then su to root
		and run make install. You are now ready to test your new Linuxconf.

		Running "make install" from the top level directory will install
		everything. Note that the environment variable RPM_BUILD_ROOT
		may be used to install in a sub-directory instead of installing
		over /bin, /usr/lib/linuxconf, etc...

	<tag/make clean/
		
		will remove whatever temporary files, object files.

	</descrip>

	Note that those command may be use in the top level directory and they
	will walk the complete tree. They may also be used in the modules
	sub-directory and all modules will be processed.

	Here are some special make targets

	<descrip>
	<tag/make clean_install/

		This tags simply erase /usr/lib/linuxconf. We use that before
		doing a make install which will be the basis for a "make package".
		Note that this is not needed when building the RPM as the RPM is
		built in a special root.

	<tag/make install-devel/

		in the top level directory will install the
		necessary headers and libraries so modules and stand-alone utilities
		may be built outside of the Linuxconf trees. Some more packaging
		is needed before a nice linuxconf-devel package may be built though.
		Anyone interested in building stand-alone utility using the Linuxconf
		toolkit is welcome to ask for help. At some point, the libraries
		will be released under the LGPL.

	<tag/make list/

		in the help.files sub-directory will update
		the various FILE_LIST file in the help.files/sources/*
		sub-directory. You must run that when you have defined new
		help file in Linuxconf or in any module. Note that this
		functionality make use of the "linuxconf --helpfile" command
		line. This means that you have compiled, linked and installed
		your new Linuxconf or new module.

	<tag/make msg/

		scans the .cc source files and update the message
		dictionary. You must use that command each time you change or
		add a MSG_U macro in the source.

		Note that if you change a message (the English text), you must
		run "make msg" and then install the binary dictionary to make
		your changes visible. The best way to do it is to go to the
		"messages" directory and do "make install".

		Note also that translators should not change message in the source
		code (unless they want to enhance the English version, send me a diff
		then)

	<tag/make msg.clean

		remove from the dictionary all message not
		referenced anymore in the C++ source (obsolete messages). After
		running this command, the revision of the dictionary is raised.
		This is done because the ordering of the binary dictionary is
		changed so previous version of Linuxconf won't operate normally
		(in fact the version guaranty they won't operate at all).

		Said differently, after doing "make msg.clean", do a "make clean"
		followed by "make" to recompile all source in that directory
		and then relink Linuxconf and install the new binary. If you
		are in a module sub-directory, just reinstall the module.

		Message dictionaries are local to each source sub-directory. So
		doing a "make msg.clean" in a directory only affect the compatibility
		of the messages in that dictionary.

		You use this when you see that the Linuxconf installation report
		some obsolete messages. Note that there is no problem with obsolete
		message in a binary dictionary. So if you are unsure about this
		topic, forget about it :-)

	<tag/make proto

		will extract the various function prototype,
		including C++ member function. You must install the
		solucorp-tools package (see below) to use that.

	<tag/make RPMREV=N buildrpm/

		in the top level directory will produce
		a new RPM (both source and binaries). I use this command every time
		I do a release. I picked the src.rpm and then rebuild it on all the
		various architecture after that step.

		Note that this command does not clean anything in the source tree.
		It grabs a copy and apply make clean on the copy.

		The RPMREV=N let you control the RPM revision. This is somewhat
		useless as it is normally 1. If you respect the pristine source
		concept, this is always 1.

	<tag/make package/

		This target is used after a "make install" and produce a tar.gz
		package. This package is suitable for slackware installation
		(and Debian until there is a DEB package). The package is produced
		right in /tmp.

	</descrip>
	
<sect1>The various Makefiles
<p>
	Linuxconf is spread in many sub-directory. This makes a lot of Makefiles.
	We have attempt to avoid redundancy in the Makefiles by using include
	file. Most Makefile include the top level rules.mak. Makefiles for modules
	further include modules/stdmod.mak.

<sect1>rules.mak
<p>
	This file contain most of the rules to manage the Linuxconf project.
	It also include the Linuxconf version number (right at the top). This
	information is not stored in any header file. It is passed on the
	compiler command line.

	rules.mak also define the standard make target clean and install.
	We use a trick here to allow each Makefile to enhance (add) these rules.
	If we look at rules.mak for the definition of the "clean" target, we
	see

	<tscreen><verb>
	clean: $(LOCAL_CLEAN)
		rm -f x *.o *.obt *.bak .bak *~ *.a *.old *.log *.nap *.nar
		@for i in $(DIRS); do make -C $$i clean  || exit 1; done
	</verb></tscreen>

	As you see, the clean target depends on another target, expressed by
	a macro called LOCAL_CLEAN. This macro is generally not defined, so
	"make clean" does only what you see above. A Makefile may simply
	define another target like this

	<tscreen><verb>
	local_clean:
		rm -f something
	</verb></tscreen>

	and then at the top of the Makefile, before the include statement which
	grabs rules.mak

	<tscreen><verb>
	LOCAL_CLEAN=local_clean
	</verb></tscreen>

	The same logic has been applied with the "make install" target. The name
	of the special macro is LOCAL_INSTALL. Both macro are optional,
	corresponding to no special handling for the current directory.

<sect>Layout of the source tree
<p>
	The source tree is made of many sub-directory. Here is an overview
	in alphabetical order.

	<descrip>
	<tag/builder/

		This is the start of a module builder. It should help those who
		want to write just a single module. Not yet working though.

	<tag/dialog/

		This is the user interface toolkit.

	<tag/diajava/

		This is the java graphical front-end. This project almost work
		but has been put on the back burner because it is considered to
		slow. This directory also contains the protocol handling part
		of the GUI protocol.

	<tag/diawxxt/

		This is the reference version of the GUI front-end. This one is
		written using the wxXt toolkit. Other front-ends exists for
		Linuxconf (gnome-linuxconf, gecko) which are not part of this
		source distribution. They conform to the following specification
		<htmlurl
			url=http://www.solucorp.qc.ca/linuxconf/tech/guiapi
			name=http://www.solucorp.qc.ca/linuxconf/tech/guiapi
		>

	<tag/help.files/

		This contains all the help screens for linuxconf and the modules.
		It follows the messages sub-directory with a somewhat flat layout.
		You have the sources sub-directory which contains one directory
		per modules/linuxconf-sub-directory. Then you have one directory
		per translation holding the same sub-directory tree.

	<tag/main/

		This contain the main for Linuxconf in main.cc as well as the main
		menu in linuxconf.cc.

	<tag/misc/

		This contains various functions and classes used everywhere in
		Linuxconf.

	<tag/messages/

		This contains the various files used to build tbe binary
		dictionaries used by linuxconf and the various modules. One
		dictionary is produced for linuxconf and one for each modules.

		The organisation of this directory is pretty flat. The source
		sub-directory contains all the .dic files for Linuxconf and the
		various modules. This is convenient to have all the .dic file
		at one place.

		Then there is one sub-directory for each translation (fr for french,
		de for deutch, etc...). Each one contains a README telling you
		who is the maintainer for this translation.

	<tag/manager/

		This is an attempt to break linuxconf into a large unprivilege
		program and a small priviled (setuid) one. Not much done yet.

	<tag/modules/

		It contains all the modules, one per sub-directory. It also
		contains the setupmod.sh script which will help you prepare
		a sub-directory for a new module.

	<tag/rpmfiles/

		The spec file used to produce the RPM for linuxconf is built
		on the fly using various rules. All the files used to build the
		spec file are located in this directory.

	<tag/vpop3d/

		It contains the various utilities needed to deliver the virtual
		domain functionality.

	<tag/xconf/

		It used to contain an X configurator. Few unused file lies there
		as well as very few general purpose functions.

	</descrip>

<sect>The solucorp-tools package
<p>
	Linuxconf sources relies on some tools built at Solucorp years ago.
	These tools used to be commercial product. I intend to publish them
	under the GPL licenses as soon as I have some spare time
	(spare time, interesting concept ?). In the mean time, you can grab
	a binary only package and use it for any project. Please do not
	distribute it until I publish a real GPL (with source) package.

	The main utility in this package is called proto. It is a sophisticated
	prototype extractor. As far as I know, nothing even scratch what it does.
	I don't think any prototype extractor is available for C++ anyway.

	The package contain full documentation on the utility (it can
	extract much more than prototypes in fact). Have fun.

</article>