Writing Filesystems - Build Environment

From Genunix

So you've downloaded the OpenSolaris ON sourcecode, you have read the OpenSolaris Developer Reference Guide, you have installed the build tools and compilers, created a workspace of yours that successfully builds via nightly, and better yet, the whole WOS runs when installed on your test system via BFU.

Congratulations - you've already made it farther than 99.9999% of the population ! If you wish to take some holidays, do that now ...

What, you're still reading ? You must be anxious to get your new filesystem project started. So what do you do next ?

Since this blog series is supposed to deliver a sample filesystem, which in accordance with political correctness, will be titled lowcarbfs here, I'll illustrate what I did. Let's begin:

1. Read Will Fiveash's introduction to the wx tool. wx is a frontend for SCCS which is used for version management in the ON sourcecode, and makes the cumbersome SCCS interface actually usable. Developing for ON without wx gives me the creeps ...
2. You now have a workspace ./osol-lowcarbfs/. Activate it:
   

   cd osol-lowcarbfs; ws `pwd`
   

   Alternatively, use bldenv.
3. Initialize wx:
   

   wx init

4. Create the following subdirectories (might need mkdir -p) within your workspace clone:
   

   usr/src/cmd/fs.d/lowcarbfs/mount/
   

   usr/src/uts/common/fs/lowcarbfs/
   

   usr/src/uts/intel/lowcarbfs/
   

   usr/src/uts/sparc/lowcarbfs/

5. Create the following Makefiles for the kernel driver:
   

   usr/src/uts/intel/lowcarbfs/Makefile
   

   usr/src/uts/sparc/lowcarbfs/Makefile
   

   These can be, for a start, copied from another Solaris filesystem kernel module. Edit the "XXFS_*" references in the Makefile to refer to lowcarbfs instead of whatever they were before. The result looks like this (comments/license stripped, the example is for intel, the sparc one will be identical apart from the 'intel' lines):

   #
   #       Path to the base of the uts directory tree (usually /usr/src/uts).
   #
   UTSBASE = ../..
   
   #
   #       Define the module and object file sets.
   #
   MODULE          = lowcarbfs
   OBJECTS         = $(LOWCARBFS_OBJS:%=$(OBJS_DIR)/%)
   LINTS           = $(LOWCARBFS_OBJS:%.o=$(LINTS_DIR)/%.ln)
   ROOTMODULE      = $(ROOT_FS_DIR)/$(MODULE)
   
   #
   #       Include common rules.
   #
   include $(UTSBASE)/intel/Makefile.intel
   
   #
   #       Define targets
   #
   ALL_TARGET      = $(BINARY)
   LINT_TARGET     = $(MODULE).lint
   INSTALL_TARGET  = $(BINARY) $(ROOTMODULE)
   
   #
   #       Default build targets.
   #
   .KEEP_STATE:
   
   def:            $(DEF_DEPS)
   
   all:            $(ALL_DEPS)
   
   clean:          $(CLEAN_DEPS)
   
   clobber:        $(CLOBBER_DEPS)
   
   lint:           $(LINT_DEPS)
   
   modlintlib:     $(MODLINTLIB_DEPS)
   
   clean.lint:     $(CLEAN_LINT_DEPS)
   
   install:        $(INSTALL_DEPS)
   
   #
   #       Include common targets.
   #
   include $(UTSBASE)/intel/Makefile.targ
   

   
   

   We've specified ROOT_FS_DIR which means the driver will end up being installed in /kernel/fs/{amd64/}lowcarbfs. We could've selected USR_FS_DIR to put it into /usr/kernel/fs instead.

6. Create the following Makefile for the userspace utilities directory:
   

   usr/src/cmd/fs.d/lowcarbfs/Makefile
   

   Again, you can copy from other filesystems; the result looks like this:
   

   #  /usr/src/cmd/lib/fs/lowcarbfs is the directory of all lowcarbfs
   #  specific commands whose executable reside in $(INSDIR).
   #
   
   SUBDIRS=        mount
   
   all:=           TARGET= all
   install:=       TARGET= install
   clean:=         TARGET= clean
   clobber:=       TARGET= clobber
   lint:=          TARGET= lint
   catalog:=       TARGET= catalog
   
   # for messaging catalog
   #
   POFILE= lowcarbfs.po
   POFILES= $(SUBDIR:%=%/%.po)
   
   .KEEP_STATE:
   
   .PARALLEL:      $(SUBDIRS)
   
   all install:    $(SUBDIRS)
   
   catalog:        $(POFILE)
   
   $(POFILE):      $(SUBDIRS)
           $(RM)   $@
           cat     $(POFILES)      > $@
   
   clean clobber lint: $(SUBDIRS)
   
   $(SUBDIRS): FRC
           @cd $@; pwd; $(MAKE) $(MFLAGS) $(TARGET)
   
   FRC:
   

7. Create the Makefile for the mount command
   

   usr/src/cmd/fs.d/lowcarbfs/mount/Makefile
   

   as before, copy an existing template. You end up with:
   

   FSTYPE=         lowcarbfs
   LIBPROG=        mount
   PROG=           $(LIBPROG)
   ROOTFS_PROG=    $(PROG)
   
   # duplicate ROOTLIBFSTYPE value needed for installation rule
   # we must define this before including Makefile.fstype
   ROOTLIBFSTYPE = $(ROOT)/usr/lib/fs/$(FSTYPE)
   $(ROOTLIBFSTYPE)/%:   $(ROOTLIBFSTYPE) %
           $(RM) $@; $(SYMLINK) ../../../../etc/fs/$(FSTYPE)/$(PROG) $@
   
   include         ../../Makefile.fstype
   include         ../../Makefile.mount
   include         ../../Makefile.mount.targ
   

   
   

   We'll add more filesystem utilities later on during the series.

8. Now use wx to set up the SCCS for the newly-created Makefiles. This is as simple as:
   

   wx create usr/src/cmd/fs.d/lowcarbfs/mount/Makefile
   

   wx create usr/src/cmd/fs.d/lowcarbfs/Makefile
   

   wx create usr/src/uts/intel/lowcarbfs/Makefile
   

   wx create usr/src/uts/sparc/lowcarbfs/Makefile
   

   You're getting errors/warnings from wx ? That's normal. It checks for the "proper" presence of #pragma ident strings and for license comment blocks. See the Best Practices section in the OpenSolaris developer references for how this is supposed to look like. You can of course, since wx is opensource as well, modify the script to perform such checks as you see them fit.