Then I realized I've had 15 years at Sun under my belt and this person's a complete newbie.
I haven't looked very closely at the Illumos build instructions, but I'm going to do some things now that will help kernel module writers (e.g. device drivers) get started without resorting to a full build right off the bat. I'll assume that you've installed the appropriate compilers and the "onbld" package so that you have a populated /opt/onbld/bin.
STEP 1: The /opt/onbld/bin/ws command:
When you go to work in an Illumos source base, your best off "entering it" via the ws command. I've hacked my .tcshrc to print a different prompt when I'm in with ws. Here, check it out:
everywhere(~)[1]% ws ws/to_mhi
Workspace : /export/home/danmcd/ws/to_mhi
Workspace Parent : /export/home/danmcd/ws/illumos-clone
Proto area ($ROOT) : /export/home/danmcd/ws/to_mhi/proto/root_i386
Parent proto area ($PARENT_ROOT) : /export/home/danmcd/ws/illumos-clone/proto/root_i386
Root of source ($SRC) : /export/home/danmcd/ws/to_mhi/usr/src
Root of test source ($TSRC) : /export/home/danmcd/ws/to_mhi/usr/ontest
Current directory ($PWD) : /export/home/danmcd/ws/to_mhi
WS-everywhere-WS(~/ws/to_mhi)[0]%
You'll notice a few things got set in the environment. What I use to alter my .tcshrc is the CODEMGR_WS variable. You should do the same in your favorite shell's config.
UPDATE: You will need to set SPRO_ROOT and BUILD_TOOLS after invoking ws. I do this already in my .tcshrc, but forgot to report it. A newer tool: bldenv, fixes this, but currently at the cost of a configuration file. There's talk of merging ws's simplicity with bldenv's completeness.
One of the key concepts in building Illumos is the "proto area". This is a version of the root filesystem that lives within your source tree. You'll see it set above. There's one per basic architecture type (i386 or sparc). When a full "nightly" build happens, the proto area gets populated with headers, libraries, commands, kernel modules, etc., and then the packaging tools sweep up their input from the proto area. The proto area contains more than what is on a running system.
You need to populate your proto area with basics (directory structures, etc.) to start.
WS-everywhere-WS(~/ws/to_mhi)[1]% cd $SRC
WS-everywhere-WS(usr/src)[0]% pwd
/export/home/danmcd/ws/to_mhi/usr/src
WS-everywhere-WS(usr/src)[0]% dmake sgs
< Go get a drink of water or coffee, it's gonna be a bit... >
WS-everywhere-WS(usr/src)[1]%
The "sgs" target sets up the proto area completely.
If you're proceeding to build, say, kernel modules, you should populate the kernel include files in the proto area.
WS-everywhere-WS(~/ws/to_mhi)[0]% cd usr/src/uts
WS-everywhere-WS(src/uts)[0]% dmake install_h
< TONS of output deleted... >
WS-everywhere-WS(src/uts)[0]%
UPDATE Fellow Illumos hacker Rich Lowe has informed me that "dmake setup" does both sgs and install_h in one fell swoop.
And then you can go and compile your kernel module. I'll use "ip" as an example:
WS-everywhere-WS(src/uts)[1]% cd intel/ip
WS-everywhere-WS(intel/ip)[0]% pwd
/export/home/danmcd/ws/to_mhi/usr/src/uts/intel/ip
WS-everywhere-WS(intel/ip)[0]% dmake
< MORE output deleted... >
WS-everywhere-WS(intel/ip)[0]%
If you want to lint-check your module, don't do the obvious "make lint" but instead do "make modlintlib". This will perform basic lint sanity without the overhead of a full crosscheck.
Now if you want to do something in userland, you'll need to do more than a simple header install. You MIGHT need to bringup libraries too, because it's possible your workspace's libraries have different versions than the machine you're actually building on.
WS-everywhere-WS(intel/ip)[0]% cd $SRC/lib
WS-everywhere-WS(src/lib)[0]%
If you utter "dmake install", it's going to be a while. You can, if you know only a certain library was altered, cd into that library and utter "dmake install" in there. For example:
WS-everywhere-WS(src/lib)[0]% cd libipsecutil
WS-everywhere-WS(lib/libipsecutil)[0]% dmake install_h
< output deleted... >
WS-everywhere-WS(lib/libipsecutil)[0]% dmake install
< MORE output deleted... >
WS-everywhere-WS(lib/libipsecutil)[0]%
Then you can go to, say, your new command, and start compiling and debugging there. Once you're done, you can exit this shell, and it will return you to your original pre-ws shell.
Hopefully this will lower some of the barriers to entry for budding Illumos hackers.
