-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathillumos-notes.txt
308 lines (265 loc) · 16.2 KB
/
illumos-notes.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
[Links]
- http://wiki.illumos.org/display/illumos/How+To+Contribute
- http://wiki.illumos.org/display/illumos/How+To+Build+illumos
- http://us-east.manta.joyent.com/rmustacc/public/iondg/workflow.html
[Setting up zpool]
- sudo zfs create rpool/export/home/illumos-dev
- sudo zfs create rpool/export/home/illumos-dev/code
- sudo ln -s ./export/home/illumos-dev/code /
- sudo chown -R $USER /export/home/illumos-dev
- sudo zfs set compression=lzjb rpool/export/home/illumos-dev
- sudo zfs set atime=off rpool/export/home/illumos-dev
- sudo zfs set sync=disabled rpool/export/home/illumos-dev
- sudo zfs create -o atime=off -o compression=gzip-9 \
rpool/export/home/illumos-dev/packages
- sudo chown -R $USER /export/home/illumos-dev
- ### NOTE: Make the symlink AFTER checking out the source:
- sudo ln -s ../../packages /export/home/illumos-dev/code/illumos-gate
[Obtaining Source]
- cd /export/home/illumos-dev/code
- git clone git://github.com/illumos-gate/illumos-gate.git
- cd /export/home/illumos-dev/code/illumos-gate
- cp /opt/onbld/env/illumos illumos.sh
- vi illumos.sh
export GATE="illumos-gate"
export CODEMGR_WS="/export/home/illumos-dev/code/$GATE"
# Default to compiling with gcc
export __GNUC=""
# Disable the shadow compiler which requires the correct version of Sun Studio
export CW_NO_SHADOW=1
[Obtaining closed binaries]
- cd /export/home/illumos-dev/code/illumos-gate
- curl -O https://download.joyent.com/pub/build/illumos/on-closed-bins.i386.tar.bz2
- curl -O https://download.joyent.com/pub/build/illumos/on-closed-bins-nd.i386.tar.bz2
- tar xjvpf on-closed-bins.i386.tar.bz2
- tar xjvpf on-closed-bins-nd.i386.tar.bz2
[Build illumos]
- cd /export/home/illumos-dev/code/illumos-gate
- /opt/onbld/bin/nightly ./illumos.sh
- cd log/
- tail -f nightly.log
22/05/14 Build:
real 268m30.885s
user 190m17.520s
sys 47m45.915s
- Using MAXJOBS = 12 building full nightly halves the build time from above:
real 82m56.917s
user 263m45.637s
sys 182m49.067s
- Using MAXJOB = 18 building full nightly is pretty much the same as above:
real 83m28.971s
user 276m52.324s
sys 180m37.146s
[Using bldenv]
- cd /export/home/illumos-dev/code/illumos-gate
- /opt/onbld/bin/bldenv -d ./illumos.sh
Build type is DEBUG
RELEASE is
VERSION is illumos-gate
RELEASE_DATE is May 2014
The top-level 'setup' target is available to build headers and tools.
Using /bin/bash as shell.
[Using cscope]
**** Problem ****
- dmake cscope.out
- cscope-fast -dq
**** Problem ****
where XXXX = bug #
webrev -o XXXX-YYYYYYYY -p HEAD^
YYYYY... = bug description
[ON Notes]
Chapter 2 - Prerequisites: http://web.archive.org/web/20130303020840/http://hub.opensolaris.org/bin/view/Community+Group+on/devref_2
- Regarding OpenSolaris Sun Studio 12u1 and gcc are required. gcc can be used as the primary compiler. I guess this means dmake can be dropped?
- Workspace and build environment variables must be set for the build to complete successfully.
- PATH needs the following entries:
/opt/SUNQWspro/bin
/opt/onbld/bin
/opt/onbld/bin/`uname -p`
- /usr/bin/ccs must also be included in your PATH
- An example PATH would be:
/usr/bin:/usr/sbin:/usr/ccs/bin:/usr/dt/bin:/usr/openwin/bin: \
/opt/onbld/bin:/opt/onbld/bin/sparc:/opt/sfw/bin:/usr/sfw/bin
- Including /usr/ucb is not recommended for the build as it is not needed.
- Adding /opt/onbld/man and /opt/SUNWspro/man to the MANPATH is also useful
Chapter 3 - The Source Tree, part 1: http://web.archive.org/web/20121229100248/http://hub.opensolaris.org/bin/view/Community+Group+on/devref_3a
- Initially the workspace contains one directory 'usr'. But after a build has been completed, proto, packages, archives and log will have also been created.
- The log directory will contain the complete output from the nightly build process: /code/illumos-core/log/log.2014-12-10.11:54/nightly.log
$ cat nightly.log | wc -l
296608
$
- The usr/src directory contains sources to buld the system but does not contain the following:
- Java
- the windowing system
- packaging tools
- installation tools
- Here they are described:
cmd : Contains sources for the executable programs and scripts including all the basic commands, daemons, startup scripts and related data. Most subdirectories are named for the command or commands then provide; however, there are some exceptions listed here.
cmd/Adm : Misc key system files, such as crontabs and data installed in /etc
cmd/cmd-crypto : Basic crytographic utilities, such as elfsign and kcfd.
cmd/cmd-inet : Network commands and daemons, including the Berkeley r-commands, PPP, telnet, the inetd super-server, and other network-related utilities.
cmd/fs.d : Utilies for checking, mounting, unmounting and analysing filesystems.
cmd/netfiles : IP port definitions and name service switch configuration files installed in /etc.
cmd/ptools : Utilities for manipulating and observing processes; based on proc(4) and libproc interfaces.
cmd/sgs : Software Generation System. Contains binary utilities such as ld(1), ar(1) and mcs(1) and dev tools such as lex(1), yacc(1) and m4(1).
common : Files which are common among cmd, lib, stand and uts. These typically include headers and sources to basic libraries used by both the kernal and user programs.
head : Userland header files. Only libc should be stored here. Other libs have their headers in their own subdirectories in lib/
lib : Libraries.
pkg : Contains a manifests subdirectory with one manifest file for each package generated from the sources. The rest of the files are used to drive package publication based on those manifests. pkg/README.pkg has more details.
prototypes : Sample files showing format and copyright notices.
psm : Platform-specific modules. Contains only OBP and most of the boot code.
stand : Standalone environment code. Used for booting e.g. code for reading from UFS and the network is here.
tools : Dev tools and sources. README.tools for more info.
ucbcmd : Commands and daemons installed into /usr/ucb.
ucbhead : Header files installed into /usr/ucb.
ucblib : Libraries installed into /usr/ucb.
uts : Kernel sources are here. (UTS = UNIX Time Sharing). Some directories of interest are below.
uts/adb : adb contained the obsolete kernel debugger macros; it is no longer supported. Directory is now empty. Use mdb(1) instead.
uts/common : All platform-independent kernel sources. Nearly all kernel source code is here.
uts/common/c2 : Auditing code to support the C2 U.S. government security standard.
uts/common/conf : System configuration parameters.
uts/common/contract : Code to support process contracts. contact(4) and libcontract(3LIB).
uts/common/cpr : CheckPoint-and-Resume support. Suspend and resume functionality.
uts/common/crypto : Kernel crypto framework. See kcfd(1M) and cryptoadm(1M).
uts/common/ctf : Code for handling Compact C Type Format data.
uts/common/disp : Dispatcher, thread handling, and scheduling classes.
uts/common/dtrace : CPU-independent dtrace(7D) kernel support.
uts/common/exec : Code for handling userland binary executable types (a.out, ELF, etc).
uts/common/fs : Filesystems.
uts/common/gssapi : Generic Security Services API.
uts/common/inet : IP networking subsystem, including IPv6.
uts/common/io : I/O subsystem. Most of this code is device drivers.
uts/common/ipp : IP Policy framework, QoS etc.
uts/common/kmdb : Kernel modular debugger (kmdb(1)).
uts/common/krtld : Kernel runtime linker/loader. Responsible for handling loadable modules and symbolresolution; it is analogous to ld.so.1 and shares code with it.
uts/common/ktli : Kernel TLI (Transport Layer Interface).
uts/common/net : Header files.
uts/common/netinet : Header files.
uts/common/nfs : NFS header files.
uts/common/os : Core OS implementation. Includes privileges, zones, timers, DDI/DKI interfaces, and high-level locking mechanisms.
uts/common/pcmcia : PCMCIA I/O subsystem and drivers.
uts/common/rpc : RPC call subsystem.
uts/common/rpcsvc : RPC header files.
uts/common/sys : Header files. Also used to build the kernel.
uts/common/syscall : System call implementations.
uts/common/tnf : Old tracing subsystem, not related to dtrace(7D).
uts/common/vm : Virtual memory subsystem.
uts/common/zmod : Compression/decompression library.
uts/i86pc : Architecture-dependent files for x86 machines.
uts/intel : ISA-dependent, architecture-independent files for x86 machines.
uts/sfmmu : Code specific to the SpitFire memory management unit (UltraSPARC).
uts/sparc : ISA-dependent, architecture-independent files for SPARC machines.
uts/sun : Sources common to all Sun implementations. Contains a small number of device drivers and some headers shipped in /usr/include/sys.
uts/sun4 : Sources common to all sun4* machine architectures.
uts/sun4u : Architecture-dependent sources for the sun4u architecture. Each system implementation has their own subdirectory.
- Makefile layout
- usr/src/Makefile : top level makefile which drives builds for various targets in each subdirectory. - usr/src/Makefile.lint : All linting from the top level is done by this makefile.
- usr/src/Makefile.master and usr/src/Makefile.master.64 : These two makefiles contain generic definitions, such as build and installation tools locations, template macros for compilers, linkers, and other tools to be used by other makefiles in defining rules, and global definitions such as the ISA and machine names that apply to this build. Makefile.master.64 contains definitions specific to 64-bit builds that override the generic definitions.
- usr/src/Makefile.msg.targ : Common targets for building message catalogues are defined here. Message catalogues provide translations of messages for g11n purposes.
- usr/src/Makefile.psm : Defines the installation locations for platform-specific modules.
- usr/src/Makefile.psm.targ : Installation target definitions for platform-specific modules.
- usr/src/Targetdirs : Set of definitions for the owner, group, permissions of each directory that will be created by the installation process.
MODULE INSTALLATION
- The install target causes binaries and libraries to be installed in the proto area. All modules are installed under $proto/kernel or $proto/usr/kernel.
- To accommodate fully functional builds for ON, even though some sources are missing, a set of closed binaries are available, and the build system has been modified to make use of them. The makefile variable CLOSED_BUILD controls whether the build system will use the prebuilt closed binaries or look for the closed sources.
- CLOSED_BUILD is typically used in makefile lines that build up the list of modules or subdirectories that are to be built. Makefile lines that start with CLOSED_BUILD, e.g.,
$(CLOSED_BUILD)DCSUBDIRS += \
$(CLOSED)/cmd/pax
are for use only when the closed sources are present.
Chapter 3 - The Source Tree: part 2 - http://web.archive.org/web/20130303020856/http://hub.opensolaris.org/bin/view/Community+Group+on/devref_3b
- Adding a new kernel module
- Imagine the module is called foofs
- Create the usr/src/uts/common/fs/foofs directory and populate it with your sources
- Edit uts/*/Makefiles.files to define the set of objects.
- Create build directories in the appropriate places. (foofs is common code, so two build directories are needed: usr/src/uts/sparc/foofs and usr/src/uts/intel/foofs.)
- In each build directory, create a makefile.
MODULE = foofs
OBJECTS = $(FOOFS_OBJS:%=$(OBJS_DIR)/%)
LINTS = $(FOOFS_OBJS:%.o=$(LINTS_DIR)/%.ln)
ROOTMODULE = $(ROOT_FS_DIR)/$(MODULE)
- Edit the parent Makefile.sparc, Makefile.intel to know about the new module
FS_KMODS += foofs
- Some library Makefile examples:
lib/libdhcputil
Example of a simple 32-bit only library.
lib/libdhcpagent
Example of a simple 32-bit only library that obtains its sources from multiple directories.
lib/ncad_addr
Example of a simple loadable module.
lib/libipmp
Example of a simple library that builds a message catalog.
lib/libdhcpsvc
Example of a Makefile hierarchy for a library and a collection of related pluggable modules.
lib/lvm
Example of a Makefile hierarchy for a collection of related libraries and pluggable modules.
Also an example of a Makefile hierarchy that supports the _dc target for domain and category specific messages.
Chapter 4 - Building ON - http://web.archive.org/web/20130301050449/http://hub.opensolaris.org/bin/view/Community+Group+on/devref_4
- Environment Variables affecting the build:
- CODEMGR_WS root of the workspace.
- SRC root of the ON source tree.
- MACH ISA of the machine.
- ROOT root of the proto area of the build.
- PARENT_ROOT proto area of the parent workspace.
- MAKEFLAGS make flags.
- SPRO_ROOT top of the compiler tree typically /opt/SUNWspro.
- SPROV_ROOT version of compiler.
- GNU_ROOT /usr/sfw gcc tree.
- __GNUC, __GNUC64 control use of gcc.
- CLOSED_IS_PRESENT whether to look for closed binaries or not.
- ON_CLOSED_BINS points to the unpacked closed binaries.
- Using nightly and bldenv:
- ON's build process entails creation of the proto area, compiling and linking binaries, generating lint libraries and linting the sources, building packages and BFU archives, and verifying headers, packaging, and proto area changes.
- nightly automates this entire process.
- nightly builds the source, generates BFU archives, generates packages, runs lint(1), does syntactic checks, and creates and checks the proto area.
- It does not do any unit testing.
- nightly uses an environment file to set variables for workspace, flags etc. Sample files are located in usr/src/tools/env.
- Using make:
- You can use make if you are working on a specific subdirectory.
- You cannot use BSD make or GNU make to build your workspace.
- Generic targets for make:
all
Build all derived objects in the object directory.
install
Install derived objects into the proto area defined by ${ROOT}.
install_h
Install header files into the proto area defined by ${ROOT}.
clean
Remove intermediate object files, but do not remove "complete" derived files such as executable programs, libraries, or kernel modules.
clobber
Remove all derived files.
check
Perform source-specific checks such as source and header style conformance.
lint
Generate lint libraries and run all appropriate lint passes against all code which would be used to build objects in the current directory.
- Proto Area:
- The install target causes binaries and headers to be installed into a hierarchy called the prototype or proto area.
- This looks like a full system install as all files and directories are relative to the workspace root.
- The proto area is useful if you need to copy specific files from the build into your live system.
- It is also compared with the parent's proto area and the packaging information by tools like protocmp and checkproto to verify that only the expected shipped files have changed as a result of your source changes.
- BFU Archives:
- cpio-format archives used to install ON on the live system.
- BFU archives are built by mkbfu.
- Packages:
- The -p option to nightly will package the files that were installed into your proto area.
Chapter 5 - Installing and Testing ON - http://web.archive.org/web/20130303044403/http://hub.opensolaris.org/bin/view/Community+Group+on/devref_5
- Cap-Eye Install - used only to install the kernel. It will place the new kernel in a nonstandard location and install only the platform-specific modules for your particular host. This allows you to test your changes without removing the normal kernel; if your new kernel does not boot or crashes, this makes recovery much easier.
- BFU - Updates both kernel and userland. Everything.
- Installing a kernel:
- Install -G kernel.foo -k sun4u
- Creates a tarfile.
- Copy /tmp/Install.username/Install.sun4u.tar to target machine and extract into root directory.
- Reboot:
(SPARC)
# reboot -- 'kernel.foo/sparcv9/unix'
(AMD64)
# reboot -- 'kernel.foo/amd64/unix'
(x86)
# reboot -- 'kernel.foo/unix'
- Using BFU to Install ON:
- BFU uses a set of cpio(1) archives to directly overwrite the existing contents of the system.
- In order to use BFU, you will need to set three additional environment variables first.
-FASTFS
This should normally be set to /opt/onbld/bin/`uname -p`/fastfs.
BFULD
This should normally be set to /opt/onbld/bin/`uname -p`/bfuld.
GZIPBIN
This should normally be set to /usr/bin/gzip.