1.\" $NetBSD: src.7,v 1.15 2018/09/23 09:21:00 maxv 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 September 23, 2018 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 algorithms 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 kern/ 279.Nx Ap s 280Kernel code, such as resource management, signal delivering, etc. 281.It Pa lib/ 282Libraries used by the kernel. 283.It Pa miscfs/ 284Drivers for file systems used to store layered data for kernel features. 285.It Pa modules/ 286Kernel components, including hardware specific drivers and upper-level drivers. 287.It Pa net/ 288Lowlevel network: protocol drivers, packet filters and access interfaces for NICs. 289.It Pa net80211/ 290Drivers for 802.11 wireless network. 291.It Pa netatalk/ 292Appletalk protocol stack 293.Xr atalk 4 . 294.It Pa netbt/ 295Bluetooth stack 296.Xr bluetooth 4 . 297.It Pa netinet/ 298IPv4 protocol stack 299.Xr ip 4 . 300.It Pa netinet6/ 301IPv6 protocol stack. 302.It Pa netipsec/ 303IPsec protocol stack 304.Xr ipsec 4 . 305.It Pa netmpls/ 306MPLS protocol stack 307.Xr mpls 4 . 308.It Pa netsmb/ 309SMB network protocol stack. 310.It Pa nfs/ 311Network file system driver. 312.It Pa opencrypto/ 313Cryptographic hardware framework 314.Xr opencrypto 9 . 315.It Pa rump/ 316Rump kernel 317.Xr rump 3 . 318.It Pa secmodel/ 319Security model framework 320.Xr secmodel 9 . 321.It Pa stand/ 322Source for several standalone programs that aren't used by 323.Nx 324currently. 325.It Pa sys/ 326Header files that get installed into 327.Pa /usr/include/sys . 328.It Pa ufs/ 329UFS file system driver. 330.It Pa uvm/ 331Virtual memory manager. 332.El 333.It Pa tests/ 334Source for test programs in 335.Pa /usr/tests . 336These tests use the 337.Xr atf 7 338test framework. 339For library routines, including system calls, the 340directory structure of the tests should follow the 341directory structure of the real source tree. 342For instance, interfaces available via the C 343library should follow: 344.Pa src/lib/libc/gen -> Pa src/tests/lib/libc/gen , 345.Pa src/lib/libc/sys -> Pa src/tests/lib/libc/sys , 346etc. 347Equivalently, all tests for userland utilities 348should try to follow their location in the source tree. 349If this can not be satisfied, the tests for 350a utility should be located under the directory to which 351the utility is installed. 352Thus, a test for 353.Xr env 1 354should go to 355.Pa src/tests/usr.bin/env . 356Likewise, a test for 357.Xr tcpdump 8 358should be in 359.Pa src/tests/usr.sbin/tcpdump , 360even though the source code for the program is located under 361.Pa src/external . 362.It Pa tools/ 363Reachover build structure for the host build tools. 364Every utility has its own directory, where its Makefile 365is located. 366.It Pa x11/ 367Reachover build structure for X11R7; the source is in 368.Pa X11SRCDIR . 369The directory structure copies the system\'s; 370every directory contains a Makefile. 371.El 372.Sh SEE ALSO 373.Xr hier 7 374.Sh HISTORY 375This file was created as a part of Google Code-in 2012/2013. 376.Sh AUTHORS 377.An -nosplit 378This manpage was written by 379.An Elvira Khabirova Aq Mt skinder0@gmail.com , 380the 381.Pa sys/ 382part by 383.An Mingzhe Wang . 384