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