1.\" $NetBSD: src.7,v 1.9 2014/10/27 11:55:08 christos Exp $ 2.\" 3.\" Copyright (c) 2012, 2013 Mingzhe Wang and Elvira Khabirova. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.Dd October 27, 2014 28.Dt SRC 7 29.Os 30.Sh NAME 31.Nm src 32.Nd layout of NetBSD sources 33.Sh DESCRIPTION 34An outline of the 35.Nx 36source code hierarchy. 37.Bl -tag -width "external/" 38.It Pa bin/ 39Critical utilities for the system and users. 40.It Pa sbin/ 41Critical utilities for the system and the superuser. 42.It Pa usr.bin/ 43Not-so critical utilities for the system and users. 44.It Pa usr.sbin/ 45Not-so critical utilities for the system and the superuser. 46.It Pa common/ 47Sources shared between kernel and userland. 48.Bl -tag -width "include/" -compact 49.It Pa dist/ 50Utilities. 51Every utility has its own subdirectory, 52where its source and Makefile are located. 53.It Pa include/ 54Include headers. 55Every group of header files has its own 56subdirectory, where it and its 57Makefile are located. 58.It Pa lib/ 59Libraries. 60Every library has its own subdirectory, 61where it and its Makefile are located. 62.El 63.It Pa compat/ 64A framework to (re)build the libraries 65shipped with 66.Nx 67for different ABI than the default for 68that platform. 69.Bl -tag -width "compat/<arch1>/<arch2>/" -compact 70.It Pa compat/<arch1>/<arch2>/ 71Every 72.Pa compat/<arch1>/<arch2>/ 73directory contains a Makefile and a makefile 74fragment for building an 75.Pa <arch2> 76compat libraries for 77.Pa <arch1> . 78E. g., 79.Pa compat/amd64/i386/ 80is where the 32-bit compat libraries for the 81amd64 port are being built. 82.It Pa compatsubdir.mk 83The list of subdirectories (the libraries and 84ld.elf_so) to build with this ABI. 85.It Pa archdirs.mk 86The list of subdirectories for each port. 87.It Pa Makefile.compat 88The basic framework to force the right paths for 89library and ld.elf_so linkage. 90.It Pa dirshack/Makefile 91A hack to get objdirs created timely. 92.El 93.It Pa crypto/ 94Cryptographic source, which may have import or 95export restrictions. 96.Bl -tag -width "external/" -compact 97.It Pa dist/ 98Original sources. 99This is deprecated; 100.Pa crypto/external/ 101should be used instead. 102.It Pa external/ 103Original sources, grouped by license, and then 104package per license. 105.Pa crypto/external/<license>/<package>/dist/ 106contain original sources for given package; 107other directories contain Makefiles and 108given package's config files. 109.El 110.It Pa dist/ 111Unmodified sources from third parties. 112This is deprecated; 113.Pa external/ 114should be used instead. 115.It Pa distrib/ 116Tools and data-files for making distributions. 117.Bl -tag -width "distrib/notes/<arch>/" -compact 118.It Pa <arch>/ 119Architecture-specific files, grouped by 120image type. 121E. g., 122.Pa distrib/<arch>/floppies/ 123contains Makefiles for making images for 124various types of floppies; 125.Pa <arch>/ramdisk/ 126contains makefiles for making ramdisks etc. 127.It Pa cdrom/ 128Was used to create bootable CD images. 129This is deprecated; 130.Pa build.sh 131\'s 132.Pa iso-image 133target should be used instead. 134.It Pa common/ 135Common files for images generation. 136.It Pa miniroot/ 137Files for miniroot. 138.It Pa notes/<arch> 139Architecture-specific parts of release notes. 140.It Pa sets/ 141Scripts for making file sets. 142.It Pa utils/ 143Utilities for installation ramdisk. 144.El 145.It Pa doc/ 146Development documentation files: changelogs, 147build readmes etc. 148.Pa doc/roadmaps/ 149contains roadmaps. 150.It Pa etc/ 151Default configuration files to be put into 152.Pa /etc . 153.Bl -tag -width "compat/<arch1>/<arch2>/" -compact 154.It Pa etc/etc.<arch>/ 155Architecture-specific config files. 156.El 157.It Pa external/ 158Unmodified sources from third parties, 159grouped by license. 160They are built with so-called "reachover" 161Makefiles which can be found in 162.Pa src/*bin/ 163hierarchies. 164Every 165.Pa external/<license>/<package>/ 166may contain: 167.Bl -tag -width "usr.sbin/" -compact 168.It Pa dist/ 169Unmodified third party source for a given package 170.It Pa bin/ 171.It Pa usr.bin/ 172.It Pa usr.sbin/ 173.It etc. 174Such subdirectories contain reachover Makefiles, 175README's and various import helper scripts. 176E. g., 177.Pa external/public-domain/ 178contains 179sources licensed under Public Domain 180license; 181.Pa external/public-domain/sqlite/dist/ 182contains original sources; 183.Pa external/public-domain/sqlite/bin/ , 184.Pa external/public-domain/sqlite/lib/ 185and 186.Pa external/public-domain/sqlite/ 187itself contain reachover Makefiles. 188.El 189.It Pa extsrc/ 190Optional developer-provided sources that are built if 191.Pa MKEXTSRC=yes , 192as a way to include extra components in the 193build. 194.It Pa games/ 195Sources for utilities/files in 196.Pa /usr/games ; 197each utility has its own subdirectory, where 198its sources and Makefiles are located. 199.It Pa gnu/ 200Sources licensed under GNU GPL. 201This is deprecated; 202.Pa external/gpl2/ 203or 204.Pa external/gpl3/ 205should be used instead. 206.Pa gnu/dists 207contains the original GNU sources plus changes that 208were submitted to maintainers and that are not 209yet published. 210Other folders contain files that are never expected 211to be submitted to the FSF (reachover Makefiles, etc.) 212.It Pa include/ 213Files to be put into 214.Pa /usr/include . 215.It Pa lib/ 216Source for libraries in 217.Pa /usr/lib 218and some scripts for them. 219Every directory contains source for given library 220and Makefiles. 221.It Pa libexec/ 222Source for utilities in 223.Pa /usr/libexec . 224Every directory contains source for given utility 225and Makefiles. 226.It Pa regress/ 227Various regression tests in 228.Pa /usr/tests . 229This is deprecated; most tests are being migrated 230into 231.Pa tests/ 232once they are migrated to the 233.Xr atf 7 234test framework. 235.It Pa rescue/ 236Makefiles for copying utilities to 237.Pa /rescue . 238.It Pa share/ 239Source for utilities/files in 240.Pa /usr/share . 241Every utility has its own subdirectory, 242where its source and Makefile are located. 243.It Pa sys/ 244Kernel source. 245.Bl -tag -width "opencrypto/" -compact 246.It Pa altq/ 247Network packet alternate queueing. 248.It Pa arch/ 249Files to specific hardware platforms. 250.It Pa coda/ 251Coda file system driver. 252.It Pa compat/ 253Support for older version 254.Nx 255binaries and 256.Pf non- Nx 257binaries. 258.It Pa conf/ 259Misc files for building kernel. 260.It Pa crypto/ 261Crypt alogorithms used by IPsec. 262.It Pa ddb/ 263Client code for local kernel debugger. 264.It Pa dev/ 265Device drivers. 266.It Pa dist/ 267Parent directory for the 268.Ox 269packet filter 270.Xr pf 4 . 271.It Pa external/ 272Sources from third parties, grouped by license. 273.It Pa fs/ 274File systems storing data on physical drives. 275.It Pa gdbscripts/ 276.Xr gdb 1 277macros. 278.It Pa ipkdb/ 279Client code for remote kernel debugger. 280.It Pa kern/ 281.Nx Ap s 282Kernel code, such as resource management, signal delivering, etc. 283.It Pa lib/ 284Libraries used by the kernel. 285.It Pa miscfs/ 286Drivers for file systems used to store layered data for kernel features. 287.It Pa modules/ 288Kernel components, including hardware specific drivers and upper-level drivers. 289.It Pa net/ 290Lowlevel network: protocol drivers, packet filters and access interfaces for NICs. 291.It Pa net80211/ 292Drivers for 802.11 wireless network. 293.It Pa netatalk/ 294Appletalk protocol stack 295.Xr atalk 4 . 296.It Pa netbt/ 297Bluetooth stack 298.Xr bluetooth 4 . 299.It Pa netinet/ 300IPv4 protocol stack 301.Xr ip 4 . 302.It Pa netinet6/ 303IPv6 protocol stack. 304.It Pa netipsec/ 305IPsec protocol stack 306.Xr ipsec 4 . 307.It Pa netisdn/ 308ISDN protocol stack 309.Xr isdn 4 . 310.It Pa netkey/ 311Key management for IPsec. 312.It Pa netmpls/ 313MPLS protocol stack 314.Xr mpls 4 . 315.It Pa netnatm/ 316Native Mode ATM protocol stack. 317.It Pa netns/ 318Xerox network protocol stack. 319.It Pa netsmb/ 320SMB network protocol stack. 321.It Pa nfs/ 322Network file system driver. 323.It Pa opencrypto/ 324Cryptographic hardware framework 325.Xr opencrypto 9 . 326.It Pa rump/ 327Rump kernel 328.Xr rump 3 . 329.It Pa secmodel/ 330Security model framework 331.Xr secmodel 9 . 332.It Pa stand/ 333Source for several standalone programs that aren't used by 334.Nx 335currently. 336.It Pa sys/ 337Header files that get installed into 338.Pa /usr/include/sys . 339.It Pa ufs/ 340UFS file system driver. 341.It Pa uvm/ 342Virtual memory manager. 343.El 344.It Pa tests/ 345Source for test programs in 346.Pa /usr/tests . 347These tests use the 348.Xr atf 7 349test framework. 350For library routines, including system calls, the 351directory structure of the tests should follow the 352directory structure of the real source tree. 353For instance, interfaces available via the C 354library should follow: 355.Pa src/lib/libc/gen -> Pa src/tests/lib/libc/gen , 356.Pa src/lib/libc/sys -> Pa src/tests/lib/libc/sys , 357etc. 358Equivalently, all tests for userland utilities 359should try to follow their location in the source tree. 360If this can not be satisfied, the tests for 361a utility should be located under the directory to which 362the utility is installed. 363Thus, a test for 364.Xr env 1 365should go to 366.Pa src/tests/usr.bin/env . 367Likewise, a test for 368.Xr tcpdump 8 369should be in 370.Pa src/tests/usr.sbin/tcpdump , 371even though the source code for the program is located under 372.Pa src/external . 373.It Pa tools/ 374Reachover build structure for the host build tools. 375Every utility has its own directory, where its Makefile 376is located. 377.It Pa x11/ 378Reachover build structure for X11R7; the source is in 379.Pa X11SRCDIR . 380The directory structure copies the system\'s; 381every directory contains a Makefile. 382.El 383.Sh SEE ALSO 384.Xr hier 7 385.Sh HISTORY 386This file was created as a part of Google Code-in 2012/2013. 387.Sh AUTHORS 388.An -nosplit 389This manpage was written by 390.An Elvira Khabirova Aq Mt skinder0@gmail.com , 391the 392.Pa sys/ 393part by 394.An Mingzhe Wang . 395