Re: [RFC] kbuild: Documentation - how to build external modules

Re: [RFC] kbuild: Documentation - how to build external modules

[sam]

>
>What about external modules that need to be configured
>using make config & co? Is that possible with this system?

No, this is not possible for now.
I have thought about a few ways of doing this.
What I plan to look at is something where the local Kconfig
file is read along with the .config for the kernel.
The user will then anly be allowed to tweak config symbols
defined for the external module, the kernel paramerets are not
visible, and cannot be modified.

But this requires some kconfig tweaking, and first priority is
to get the basic funtionality working so all (most) people
are happy with it.

If anyone has better ideas for handling Kconfig files for external
modules please tell so.

  Sam

RE: [RFC] kbuild: Documentation - how to build external modules

[Peter Kjellerstedt]

> -----Original Message-----
> From: sam@ravnborg.org [mailto:sam@ravnborg.org] 
> Sent: 21 April 2004 12:40
> To: Peter Kjellerstedt
> Cc: Sam Ravnborg; linux-kernel@vger.kernel.org
> Subject: Re: [RFC] kbuild: Documentation - how to build 
> external modules
> 
> >What about external modules that need to be configured
> >using make config & co? Is that possible with this system?
> 
> No, this is not possible for now.
> I have thought about a few ways of doing this.
> What I plan to look at is something where the local Kconfig
> file is read along with the .config for the kernel.
> The user will then anly be allowed to tweak config symbols
> defined for the external module, the kernel paramerets are not
> visible, and cannot be modified.

This sounds like what I was looking for.

> But this requires some kconfig tweaking, and first priority is
> to get the basic funtionality working so all (most) people
> are happy with it.

Well, we are still using 2.4, so it is no problem for us yet.
Better get the basics working first. :)

> If anyone has better ideas for handling Kconfig files for external
> modules please tell so.
> 
>   Sam

//Peter

RE: [RFC] kbuild: Documentation - how to build external modules

[Peter Kjellerstedt]

> -----Original Message-----
> From: linux-kernel-owner@vger.kernel.org 
> [mailto:linux-kernel-owner@vger.kernel.org] On Behalf Of Sam Ravnborg
> Sent: Tuesday, April 20, 2004 23:52
> To: linux-kernel@vger.kernel.org
> Subject: [RFC] kbuild: Documentation - how to build external modules
> 
> This is just first wrap-up of some text about building 
> external modules. There are a few unfinished chapters - 
> but's too late today.
> 
> Please let me know what you expect to see in here - which is 
> not covered eiter direct or via an empty heading.
> 
> 	Sam

What about external modules that need to be configured
using make config & co? Is that possible with this system?

//Peter

[RFC] kbuild: Documentation - how to build external modules

[Sam Ravnborg]

This is just first wrap-up of some text about building external modules.
There are a few unfinished chapters - but's too late today.

Please let me know what you expect to see in here - which is not covered
eiter direct or via an empty heading.

	Sam

Building external modules
=========================
kbuild offers functionality to build external modules, with the
prerequisite that there is a pre-built kernel avialable with full source.
A subset of the targets available when building the kernel is available
when building an external module.


Building the module
-------------------
The command looks like his:

	make -C <path to kernel src> M=$PWD

For the above command to succeed the kernel must have been built with
modules enabled.

To install the modules just being built:

	make -C <path to kernel src> M=$PWD modules_install

More complex examples later, the above should get you going in most cases.


Available targets:
- - - - - - - - - 
make -C $KDIR M=$PWD
	Same as if 'modules' was specified. See description of
	modules target below.

make -C $KDIR M=$PWD modules
	Will build the module(s) located in current directory. All output
	files will be located in the same directory as the module source.
	No attemps are made to update the kernel source, and it is
	expected that a successfully make has been executed
	for the kernel.

make -C $KDIR M=$PWD modules_install
	Install the external module(s)

make -C $KDIR M=$PWD clean
	Remove all generated files in current directory

Available options:
- - - - - - - - - 
make -C $KDIR
	Used to specify where to find the kernel source.
	'$KDIR' represent the directory where the kernel source is.
	Make will actually change directory to the specified directory
	when executed.

make -C $KDIR M=$PWD
	M= is used to tell kbuild that an external module is being built.
	The option given to M= is the directory where the external
	module is located.
	When an external module is being built only a subset of the
	usual targets are avialable.

make -C $KDIR SUBDIRS=$PWD
	Same as M=. The SUBDIRS= syntax is kept for backwards compatibility.

make -C $KDIR M=$PWD help
	help will list the available target when building external
	modules.


A more advanced example
- - - - - - - - - - - -
This example shows a setup where a distribution has wisely decided
to separate kernel source and output files:

Kernel src:
/usr/src/linux-<kernel-version>/

Output from a kernel compile, including .config:
/lib/modules/linux-<kernel-version>/build/

External module to be compiled:
/home/user/module/src/

To compile the module located in the directory above use the
following command:

	cd /home/user/module/src
	make -C /usr/src/linux-<kernel-version> \
	O=/lib/modules/linux-<kernel-version>/build \
	M=$PWD

Then to install the module use the following command:

	make -C /usr/src/linux-<kernel-version> \
		O=/lib/modules/linux-<kernel-version>/build \
		M=$PWD modules_install

The above are rather long commands, and the following chapter
lists a few tricks to make it all easier.

Tricks to make it easy
---------------------
TODO: .... This need to be rewritten......

A make line with several parameters becomes tiresome and errorprone
and what follows here is a little trick to make it possible to build
a module only using a single 'make' command.

Create a makefile named 'Makefile' with the following content:
---> Makefile:

all:
	$(MAKE) -C /home/sam/src/kernel/v2.6 M=$(PWD) \
			$(filter-out all,$(MAKECMDGOALS))

obj-m := module.o
---> End of Makefile

When make is invoked it will see the all: rule, and simply call make again with the right parameters.

If a driver is being developed that is targeted for inclusion in the main kernel, an idea is to seperate out the all: rule to a Makefile nemed makefile (lower capital m) like this:

---> makefile
all:
	$(MAKE) -f Makefile -C /home/sam/src/kernel/v2.6 \
	        M=$(PWD) $(MAKECMDGOALS)

---> End of makefile

The kbuild makefile will include only a single statement:
---> Makefile:

obj-m := module.o

---> End of Makefile
When executing make, it looks for a file named makefile, before a
file named Makefile. Therefor make will pick up the file named with lower capital 'm'.


Prepare the kernel for building external modules
------------------------------------------------
When building external modules the kernel is expected to be prepared.
This includes the precense of certain binaries, the kernel configuration
and the symlink to include/asm.
To do this a convinient target is made:

	make modules_prepare

For a typical distribution this would look like the follwoing:

	make modules_prepare O=/lib/modules/linux-<kernel version>/build


TODO: Fill out the following chapters

Module versioning
-----------------

Local include files
-------------------
CLFAGS := include ...

Binary only .o files
--------------------
Use _shipped ...