1*11be35a1SLionel Sambuc.\" Copyright 2012 Google Inc. 2*11be35a1SLionel Sambuc.\" All rights reserved. 3*11be35a1SLionel Sambuc.\" 4*11be35a1SLionel Sambuc.\" Redistribution and use in source and binary forms, with or without 5*11be35a1SLionel Sambuc.\" modification, are permitted provided that the following conditions are 6*11be35a1SLionel Sambuc.\" met: 7*11be35a1SLionel Sambuc.\" 8*11be35a1SLionel Sambuc.\" * Redistributions of source code must retain the above copyright 9*11be35a1SLionel Sambuc.\" notice, this list of conditions and the following disclaimer. 10*11be35a1SLionel Sambuc.\" * Redistributions in binary form must reproduce the above copyright 11*11be35a1SLionel Sambuc.\" notice, this list of conditions and the following disclaimer in the 12*11be35a1SLionel Sambuc.\" documentation and/or other materials provided with the distribution. 13*11be35a1SLionel Sambuc.\" * Neither the name of Google Inc. nor the names of its contributors 14*11be35a1SLionel Sambuc.\" may be used to endorse or promote products derived from this software 15*11be35a1SLionel Sambuc.\" without specific prior written permission. 16*11be35a1SLionel Sambuc.\" 17*11be35a1SLionel Sambuc.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 18*11be35a1SLionel Sambuc.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 19*11be35a1SLionel Sambuc.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 20*11be35a1SLionel Sambuc.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 21*11be35a1SLionel Sambuc.\" OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 22*11be35a1SLionel Sambuc.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 23*11be35a1SLionel Sambuc.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 24*11be35a1SLionel Sambuc.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 25*11be35a1SLionel Sambuc.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 26*11be35a1SLionel Sambuc.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 27*11be35a1SLionel Sambuc.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 28*11be35a1SLionel Sambuc.Dd September 9, 2012 29*11be35a1SLionel Sambuc.Dt KYUA-BUILD-ROOT 7 30*11be35a1SLionel Sambuc.Os 31*11be35a1SLionel Sambuc.Sh NAME 32*11be35a1SLionel Sambuc.Nm build-root 33*11be35a1SLionel Sambuc.Nd Mechanics of build directories 34*11be35a1SLionel Sambuc.Sh DESCRIPTION 35*11be35a1SLionel Sambuc.Em Build directories 36*11be35a1SLionel Sambuc(or object directories, target directories, product directories, etc.) is 37*11be35a1SLionel Sambucthe concept that allows a developer to keep the source tree clean from 38*11be35a1SLionel Sambucbuild products by asking the build system to place such build products 39*11be35a1SLionel Sambucunder a separate subtree. 40*11be35a1SLionel Sambuc.Pp 41*11be35a1SLionel SambucMost build systems today support build directories. For example, the GNU 42*11be35a1SLionel SambucAutomake/Autoconf build system exposes such concept when invoked as 43*11be35a1SLionel Sambucfollows: 44*11be35a1SLionel Sambuc.Bd -literal -offset indent 45*11be35a1SLionel Sambuc$ cd my-project-1.0 46*11be35a1SLionel Sambuc$ mkdir build 47*11be35a1SLionel Sambuc$ cd build 48*11be35a1SLionel Sambuc$ ../configure 49*11be35a1SLionel Sambuc$ make 50*11be35a1SLionel Sambuc.Ed 51*11be35a1SLionel Sambuc.Pp 52*11be35a1SLionel SambucUnder such invocation, all the results of the build are left in the 53*11be35a1SLionel Sambuc.Pa my-project-1.0/build/ 54*11be35a1SLionel Sambucsubdirectory while maintaining the contents of 55*11be35a1SLionel Sambuc.Pa my-project-1.0/ 56*11be35a1SLionel Sambucintact. 57*11be35a1SLionel Sambuc.Pp 58*11be35a1SLionel SambucBecause build directories are an integral part of most build systems, and 59*11be35a1SLionel Sambucbecause they are a tool that developers use frequently, 60*11be35a1SLionel Sambuc.Xr kyua 1 61*11be35a1SLionel Sambucsupports build directories too. This manifests in the form of 62*11be35a1SLionel Sambuc.Xr kyua 1 63*11be35a1SLionel Sambucbeing able to run tests from build directories while reading the (often 64*11be35a1SLionel Sambucimmutable) test suite definition from the source tree. 65*11be35a1SLionel Sambuc.Pp 66*11be35a1SLionel SambucOne important property of build directories is that they follow (or need to 67*11be35a1SLionel Sambucfollow) the exact same layout as the source tree. For example, consider 68*11be35a1SLionel Sambucthe following directory listings: 69*11be35a1SLionel Sambuc.Bd -literal -offset indent 70*11be35a1SLionel Sambucsrc/Kyuafile 71*11be35a1SLionel Sambucsrc/bin/ls/ 72*11be35a1SLionel Sambucsrc/bin/ls/Kyuafile 73*11be35a1SLionel Sambucsrc/bin/ls/ls.c 74*11be35a1SLionel Sambucsrc/bin/ls/ls_test.c 75*11be35a1SLionel Sambucsrc/sbin/su/ 76*11be35a1SLionel Sambucsrc/sbin/su/Kyuafile 77*11be35a1SLionel Sambucsrc/sbin/su/su.c 78*11be35a1SLionel Sambucsrc/sbin/su/su_test.c 79*11be35a1SLionel Sambuc 80*11be35a1SLionel Sambucobj/bin/ls/ 81*11be35a1SLionel Sambucobj/bin/ls/ls* 82*11be35a1SLionel Sambucobj/bin/ls/ls_test* 83*11be35a1SLionel Sambucobj/sbin/su/ 84*11be35a1SLionel Sambucobj/sbin/su/su* 85*11be35a1SLionel Sambucobj/sbin/su/su_test* 86*11be35a1SLionel Sambuc.Ed 87*11be35a1SLionel Sambuc.Pp 88*11be35a1SLionel SambucNote how the directory layout within 89*11be35a1SLionel Sambuc.Pa src/ 90*11be35a1SLionel Sambucmatches that of 91*11be35a1SLionel Sambuc.Pa obj/ . 92*11be35a1SLionel SambucThe 93*11be35a1SLionel Sambuc.Pa src/ 94*11be35a1SLionel Sambucdirectory contains only source files and the definition of the test suite 95*11be35a1SLionel Sambuc(the Kyuafiles), while the 96*11be35a1SLionel Sambuc.Pa obj/ 97*11be35a1SLionel Sambucdirectory contains only the binaries generated during a build. 98*11be35a1SLionel Sambuc.Pp 99*11be35a1SLionel SambucAll commands that deal with the workspace support the 100*11be35a1SLionel Sambuc.Fl -build-root Ar path 101*11be35a1SLionel Sambucoption. When this option is provided, the directory specified by the 102*11be35a1SLionel Sambucoption is considered to be the root of the build directory. For example, 103*11be35a1SLionel Sambucconsidering our previous fake tree layout, we could invoke 104*11be35a1SLionel Sambuc.Xr kyua-test 1 105*11be35a1SLionel Sambucas any of the following: 106*11be35a1SLionel Sambuc.Bd -literal -offset indent 107*11be35a1SLionel Sambuc$ kyua test --kyuafile=src/Kyuafile --build-root=obj 108*11be35a1SLionel Sambuc$ cd src && kyua test --build-root=../obj 109*11be35a1SLionel Sambuc.Ed 110*11be35a1SLionel Sambuc.Sh SEE ALSO 111*11be35a1SLionel Sambuc.Xr kyua 1 , 112*11be35a1SLionel Sambuc.Xr kyua-debug 1 , 113*11be35a1SLionel Sambuc.Xr kyua-list 1 , 114*11be35a1SLionel Sambuc.Xr kyua-test 1 115