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