1.\" $NetBSD: src.7,v 1.16 2020/05/14 16:32:57 snj 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 14, 2020 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> . 78For example, 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. 121For example, 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. 160Every 161.Pa external/<license>/<package>/ 162may contain: 163.Bl -tag -width "usr.sbin/" -compact 164.It Pa dist/ 165Unmodified third party source for a given package 166.It Pa bin/ 167.It Pa usr.bin/ 168.It Pa usr.sbin/ 169.It etc. 170Such subdirectories contain reachover Makefiles, 171README's and various import helper scripts. 172For example, 173.Pa external/public-domain/ 174contains 175sources licensed under Public Domain 176license; 177.Pa external/public-domain/sqlite/dist/ 178contains original sources; 179.Pa external/public-domain/sqlite/bin/ , 180.Pa external/public-domain/sqlite/lib/ 181and 182.Pa external/public-domain/sqlite/ 183itself contain reachover Makefiles. 184.El 185.It Pa extsrc/ 186Optional developer-provided sources that are built if 187.Pa MKEXTSRC=yes , 188as a way to include extra components in the 189build. 190.It Pa games/ 191Sources for utilities/files in 192.Pa /usr/games ; 193each utility has its own subdirectory, where 194its sources and Makefiles are located. 195.It Pa include/ 196Files to be put into 197.Pa /usr/include . 198.It Pa lib/ 199Source for libraries in 200.Pa /usr/lib 201and some scripts for them. 202Every directory contains source for given library 203and Makefiles. 204.It Pa libexec/ 205Source for utilities in 206.Pa /usr/libexec . 207Every directory contains source for given utility 208and Makefiles. 209.It Pa regress/ 210Various regression tests in 211.Pa /usr/tests . 212This is deprecated; most tests are being migrated 213into 214.Pa tests/ 215once they are migrated to the 216.Xr atf 7 217test framework. 218.It Pa rescue/ 219Makefiles for copying utilities to 220.Pa /rescue . 221.It Pa share/ 222Source for utilities/files in 223.Pa /usr/share . 224Every utility has its own subdirectory, 225where its source and Makefile are located. 226.It Pa sys/ 227Kernel source. 228.Bl -tag -width "opencrypto/" -compact 229.It Pa altq/ 230Network packet alternate queueing. 231.It Pa arch/ 232Files to specific hardware platforms. 233.It Pa coda/ 234Coda file system driver. 235.It Pa compat/ 236Support for older version 237.Nx 238binaries and 239.Pf non- Nx 240binaries. 241.It Pa conf/ 242Misc files for building kernel. 243.It Pa crypto/ 244Crypt algorithms used by IPsec. 245.It Pa ddb/ 246Client code for local kernel debugger. 247.It Pa dev/ 248Device drivers. 249.It Pa dist/ 250Parent directory for the 251.Ox 252packet filter 253.Xr pf 4 . 254.It Pa external/ 255Sources from third parties, grouped by license. 256.It Pa fs/ 257File systems storing data on physical drives. 258.It Pa gdbscripts/ 259.Xr gdb 1 260macros. 261.It Pa kern/ 262.Nx Ap s 263Kernel code, such as resource management, signal delivering, etc. 264.It Pa lib/ 265Libraries used by the kernel. 266.It Pa miscfs/ 267Drivers for file systems used to store layered data for kernel features. 268.It Pa modules/ 269Kernel components, including hardware specific drivers and upper-level drivers. 270.It Pa net/ 271Lowlevel network: protocol drivers, packet filters and access interfaces for NICs. 272.It Pa net80211/ 273Drivers for 802.11 wireless network. 274.It Pa netatalk/ 275Appletalk protocol stack 276.Xr atalk 4 . 277.It Pa netbt/ 278Bluetooth stack 279.Xr bluetooth 4 . 280.It Pa netcan/ 281Controller Area Network stack 282.Xr can 4 . 283.It Pa netinet/ 284IPv4 protocol stack 285.Xr ip 4 . 286.It Pa netinet6/ 287IPv6 protocol stack. 288.It Pa netipsec/ 289IPsec protocol stack 290.Xr ipsec 4 . 291.It Pa netmpls/ 292MPLS protocol stack 293.Xr mpls 4 . 294.It Pa nfs/ 295Network file system driver. 296.It Pa opencrypto/ 297Cryptographic hardware framework 298.Xr opencrypto 9 . 299.It Pa rump/ 300Rump kernel 301.Xr rump 3 . 302.It Pa secmodel/ 303Security model framework 304.Xr secmodel 9 . 305.It Pa stand/ 306Source for several standalone programs that aren't used by 307.Nx 308currently. 309.It Pa sys/ 310Header files that get installed into 311.Pa /usr/include/sys . 312.It Pa ufs/ 313UFS file system driver. 314.It Pa uvm/ 315Virtual memory manager. 316.El 317.It Pa tests/ 318Source for test programs in 319.Pa /usr/tests . 320These tests use the 321.Xr atf 7 322test framework. 323For library routines, including system calls, the 324directory structure of the tests should follow the 325directory structure of the real source tree. 326For instance, interfaces available via the C 327library should follow: 328.Pa src/lib/libc/gen -> Pa src/tests/lib/libc/gen , 329.Pa src/lib/libc/sys -> Pa src/tests/lib/libc/sys , 330etc. 331Equivalently, all tests for userland utilities 332should try to follow their location in the source tree. 333If this can not be satisfied, the tests for 334a utility should be located under the directory to which 335the utility is installed. 336Thus, a test for 337.Xr env 1 338should go to 339.Pa src/tests/usr.bin/env . 340Likewise, a test for 341.Xr tcpdump 8 342should be in 343.Pa src/tests/usr.sbin/tcpdump , 344even though the source code for the program is located under 345.Pa src/external . 346.It Pa tools/ 347Reachover build structure for the host build tools. 348Every utility has its own directory, where its Makefile 349is located. 350.It Pa x11/ 351Reachover build structure for X11R7; the source is in 352.Pa X11SRCDIR . 353The directory structure copies the system\'s; 354every directory contains a Makefile. 355.El 356.Sh SEE ALSO 357.Xr hier 7 358.Sh HISTORY 359This file was created as a part of Google Code-in 2012/2013. 360.Sh AUTHORS 361.An -nosplit 362This manpage was written by 363.An Elvira Khabirova Aq Mt skinder0@gmail.com , 364the 365.Pa sys/ 366part by 367.An Mingzhe Wang . 368