1# FS (filesystem) module 2 3This module provides functions to inspect the file system. It is 4available starting with version 0.53.0. 5 6## File lookup rules 7 8Non-absolute paths are looked up relative to the directory where the 9current `meson.build` file is. 10 11If specified, a leading `~` is expanded to the user home directory. 12Environment variables are not available as is the rule throughout Meson. 13That is, $HOME, %USERPROFILE%, $MKLROOT, etc. have no meaning to the Meson 14filesystem module. If needed, pass such variables into Meson via command 15line options in `meson_options.txt`, native-file or cross-file. 16 17Where possible, symlinks and parent directory notation are resolved to an 18absolute path. 19 20### exists 21 22Takes a single string argument and returns true if an entity with that 23name exists on the file system. This can be a file, directory or a 24special entry such as a device node. 25 26### is_dir 27 28Takes a single string argument and returns true if a directory with 29that name exists on the file system. 30 31### is_file 32 33Takes a single string argument and returns true if an file with that 34name exists on the file system. 35 36### is_symlink 37 38Takes a single string argument and returns true if the path pointed to 39by the string is a symbolic link. 40 41## File Parameters 42 43### is_absolute 44 45*since 0.54.0* 46 47Return a boolean indicating if the path string specified is absolute, WITHOUT expanding `~`. 48 49Examples: 50 51```meson 52fs.is_absolute('~') # false 53 54home = fs.expanduser('~') 55fs.is_absolute(home) # true 56 57fs.is_absolute(home / 'foo') # true, even if ~/foo doesn't exist 58 59fs.is_absolute('foo/bar') # false, even if ./foo/bar exists 60``` 61 62### hash 63 64The `fs.hash(filename, hash_algorithm)` method returns a string containing 65the hexidecimal `hash_algorithm` digest of a file. 66`hash_algorithm` is a string; the available hash algorithms include: 67md5, sha1, sha224, sha256, sha384, sha512. 68 69### size 70 71The `fs.size(filename)` method returns the size of the file in integer bytes. 72 73### is_samepath 74 75The `fs.is_samepath(path1, path2)` returns boolean `true` if both paths resolve to the same path. 76For example, suppose path1 is a symlink and path2 is a relative path. 77If path1 can be resolved to path2, then `true` is returned. 78If path1 is not resolved to path2, `false` is returned. 79If path1 or path2 do not exist, `false` is returned. 80 81Examples: 82 83```meson 84x = 'foo.txt' 85y = 'sub/../foo.txt' 86z = 'bar.txt' # a symlink pointing to foo.txt 87j = 'notafile.txt' # non-existant file 88 89fs.is_samepath(x, y) # true 90fs.is_samepath(x, z) # true 91fs.is_samepath(x, j) # false 92 93p = 'foo/bar' 94q = 'foo/bar/baz/..' 95r = 'buz' # a symlink pointing to foo/bar 96s = 'notapath' # non-existant directory 97 98fs.is_samepath(p, q) # true 99fs.is_samepath(p, r) # true 100fs.is_samepath(p, s) # false 101``` 102 103## Filename modification 104 105The files need not actually exist yet for these path string manipulation methods. 106 107### expanduser 108 109*since 0.54.0* 110 111A path string with a leading `~` is expanded to the user home directory 112 113Examples: 114 115```meson 116fs.expanduser('~') # user home directory 117 118fs.expanduser('~/foo') # <homedir>/foo 119``` 120 121### as_posix 122 123*since 0.54.0* 124 125`fs.as_posix(path)` assumes a Windows path, even if on a Unix-like system. 126Thus, all `'\'` or `'\\'` are turned to '/', even if you meant to escape a character. 127 128Examples 129 130```meson 131fs.as_posix('\\') == '/' # true 132fs.as_posix('\\\\') == '/' # true 133 134fs.as_posix('foo\\bar/baz') == 'foo/bar/baz' # true 135``` 136 137### replace_suffix 138 139The `replace_suffix` method is a *string manipulation* convenient for filename modifications. 140It allows changing the filename suffix like: 141 142#### swap suffix 143 144```meson 145original = '/opt/foo.ini' 146new = fs.replace_suffix(original, '.txt') # /opt/foo.txt 147``` 148 149#### add suffix 150 151```meson 152original = '/opt/foo' 153new = fs.replace_suffix(original, '.txt') # /opt/foo.txt 154``` 155 156#### compound suffix swap 157 158```meson 159original = '/opt/foo.dll.a' 160new = fs.replace_suffix(original, '.so') # /opt/foo.dll.so 161``` 162 163#### delete suffix 164 165```meson 166original = '/opt/foo.dll.a' 167new = fs.replace_suffix(original, '') # /opt/foo.dll 168``` 169 170### parent 171 172Returns the parent directory (i.e. dirname). 173 174```meson 175new = fs.parent('foo/bar') # foo 176new = fs.parent('foo/bar/baz.dll') # foo/bar 177``` 178 179### name 180 181Returns the last component of the path (i.e. basename). 182 183```meson 184fs.name('foo/bar/baz.dll.a') # baz.dll.a 185``` 186 187### stem 188 189*since 0.54.0* 190 191Returns the last component of the path, dropping the last part of the suffix 192 193```meson 194fs.stem('foo/bar/baz.dll') # baz 195fs.stem('foo/bar/baz.dll.a') # baz.dll 196``` 197