1.\" $NetBSD: src.7,v 1.10 2015/05/21 01:05:33 ozaki-r 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 May 21, 2015 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 netsmb/ 318SMB network protocol stack. 319.It Pa nfs/ 320Network file system driver. 321.It Pa opencrypto/ 322Cryptographic hardware framework 323.Xr opencrypto 9 . 324.It Pa rump/ 325Rump kernel 326.Xr rump 3 . 327.It Pa secmodel/ 328Security model framework 329.Xr secmodel 9 . 330.It Pa stand/ 331Source for several standalone programs that aren't used by 332.Nx 333currently. 334.It Pa sys/ 335Header files that get installed into 336.Pa /usr/include/sys . 337.It Pa ufs/ 338UFS file system driver. 339.It Pa uvm/ 340Virtual memory manager. 341.El 342.It Pa tests/ 343Source for test programs in 344.Pa /usr/tests . 345These tests use the 346.Xr atf 7 347test framework. 348For library routines, including system calls, the 349directory structure of the tests should follow the 350directory structure of the real source tree. 351For instance, interfaces available via the C 352library should follow: 353.Pa src/lib/libc/gen -> Pa src/tests/lib/libc/gen , 354.Pa src/lib/libc/sys -> Pa src/tests/lib/libc/sys , 355etc. 356Equivalently, all tests for userland utilities 357should try to follow their location in the source tree. 358If this can not be satisfied, the tests for 359a utility should be located under the directory to which 360the utility is installed. 361Thus, a test for 362.Xr env 1 363should go to 364.Pa src/tests/usr.bin/env . 365Likewise, a test for 366.Xr tcpdump 8 367should be in 368.Pa src/tests/usr.sbin/tcpdump , 369even though the source code for the program is located under 370.Pa src/external . 371.It Pa tools/ 372Reachover build structure for the host build tools. 373Every utility has its own directory, where its Makefile 374is located. 375.It Pa x11/ 376Reachover build structure for X11R7; the source is in 377.Pa X11SRCDIR . 378The directory structure copies the system\'s; 379every directory contains a Makefile. 380.El 381.Sh SEE ALSO 382.Xr hier 7 383.Sh HISTORY 384This file was created as a part of Google Code-in 2012/2013. 385.Sh AUTHORS 386.An -nosplit 387This manpage was written by 388.An Elvira Khabirova Aq Mt skinder0@gmail.com , 389the 390.Pa sys/ 391part by 392.An Mingzhe Wang . 393