Debian Codegraph @

subprojects/meson-docs/docs/markdown/Fs-module.md

raw
1 # FS (filesystem) module
2
3 This module provides functions to inspect the file system. It is
4 available starting with version 0.53.0.
5
6 Since 0.59.0, all functions accept `files()` objects if they can do something
7 useful with them (this excludes `exists`, `is_dir`, `is_file`, `is_absolute`
8 since a `files()` object is always the absolute path to an existing file).
9
10 ## Usage
11
12 The module may be imported as follows:
13
14 ``` meson
15 fs = [[#import]]('fs')
16 ```
17
18 ## File lookup rules
19
20 Non-absolute paths are looked up relative to the directory where the
21 current `meson.build` file is.
22
23 If specified, a leading `~` is expanded to the user home directory.
24 Environment variables are not available as is the rule throughout Meson.
25 That is, $HOME, %USERPROFILE%, $MKLROOT, etc. have no meaning to the Meson
26 filesystem module. If needed, pass such variables into Meson via command
27 line options in `meson.options`, native-file or cross-file.
28
29 Where possible, symlinks and parent directory notation are resolved to an
30 absolute path.
31
32 ### exists
33
34 Takes a single string argument and returns true if an entity with that
35 name exists on the file system. This can be a file, directory or a
36 special entry such as a device node.
37
38 ### is_dir
39
40 Takes a single string argument and returns true if a directory with
41 that name exists on the file system.
42
43 ### is_file
44
45 Takes a single string argument and returns true if an file with that
46 name exists on the file system.
47
48 ### is_symlink
49
50 Takes a single string or (since 0.59.0) `files()` argument and returns true if
51 the path pointed to by the string is a symbolic link.
52
53 ## File Parameters
54
55 ### is_absolute
56
57 *since 0.54.0*
58
59 Return a boolean indicating if the path string or (since 0.59.0) `files()`
60 specified is absolute, WITHOUT expanding `~`.
61
62 Examples:
63
64 ```meson
65 fs.is_absolute('~') # false
66
67 home = fs.expanduser('~')
68 fs.is_absolute(home) # true
69
70 fs.is_absolute(home / 'foo') # true, even if ~/foo doesn't exist
71
72 fs.is_absolute('foo/bar') # false, even if ./foo/bar exists
73 ```
74
75 ### hash
76
77 The `fs.hash(filename, hash_algorithm)` method returns a string containing
78 the hexadecimal `hash_algorithm` digest of a file.
79 `hash_algorithm` is a string; the available hash algorithms include:
80 md5, sha1, sha224, sha256, sha384, sha512.
81
82 ### size
83
84 The `fs.size(filename)` method returns the size of the file in integer bytes.
85
86 ### is_samepath
87
88 The `fs.is_samepath(path1, path2)` returns boolean `true` if both
89 paths resolve to the same path. For example, suppose path1 is a
90 symlink and path2 is a relative path. If `path1` can be resolved to
91 `path2`, then `true` is returned. If `path1` is not resolved to
92 `path2`, `false` is returned. If `path1` or `path2` do not exist,
93 `false` is returned.
94
95 Examples:
96
97 ```meson
98 x = 'foo.txt'
99 y = 'sub/../foo.txt'
100 z = 'bar.txt' # a symlink pointing to foo.txt
101 j = 'notafile.txt' # nonexistent file
102
103 fs.is_samepath(x, y) # true
104 fs.is_samepath(x, z) # true
105 fs.is_samepath(x, j) # false
106
107 p = 'foo/bar'
108 q = 'foo/bar/baz/..'
109 r = 'buz' # a symlink pointing to foo/bar
110 s = 'notapath' # nonexistent directory
111
112 fs.is_samepath(p, q) # true
113 fs.is_samepath(p, r) # true
114 fs.is_samepath(p, s) # false
115 ```
116
117 ## Filename modification
118
119 The files need not actually exist yet for these path string
120 manipulation methods.
121
122 ### expanduser
123
124 *since 0.54.0*
125
126 A path string with a leading `~` is expanded to the user home
127 directory
128
129 Examples:
130
131 ```meson
132 fs.expanduser('~') # user home directory
133
134 fs.expanduser('~/foo') # <homedir>/foo
135 ```
136
137 ### as_posix
138
139 *since 0.54.0*
140
141 `fs.as_posix(path)` assumes a Windows path, even if on a Unix-like
142 system. Thus, all `'\'` or `'\\'` are turned to '/', even if you meant
143 to escape a character.
144
145 Examples
146
147 ```meson
148 fs.as_posix('\\') == '/' # true
149 fs.as_posix('\\\\') == '/' # true
150
151 fs.as_posix('foo\\bar/baz') == 'foo/bar/baz' # true
152 ```
153
154 ### replace_suffix
155
156 The `replace_suffix` method is a *string manipulation* convenient for
157 filename modifications. It allows changing the filename suffix like:
158
159 #### swap suffix
160
161 ```meson
162 original = '/opt/foo.ini'
163 new = fs.replace_suffix(original, '.txt') # /opt/foo.txt
164 ```
165
166 #### add suffix
167
168 ```meson
169 original = '/opt/foo'
170 new = fs.replace_suffix(original, '.txt') # /opt/foo.txt
171 ```
172
173 #### compound suffix swap
174
175 ```meson
176 original = '/opt/foo.dll.a'
177 new = fs.replace_suffix(original, '.so') # /opt/foo.dll.so
178 ```
179
180 #### delete suffix
181
182 ```meson
183 original = '/opt/foo.dll.a'
184 new = fs.replace_suffix(original, '') # /opt/foo.dll
185 ```
186
187 ### parent
188
189 Returns the parent directory (i.e. dirname).
190
191 ```meson
192 new = fs.parent('foo/bar') # foo
193 new = fs.parent('foo/bar/baz.dll') # foo/bar
194 ```
195
196 ### name
197
198 Returns the last component of the path (i.e. basename).
199
200 ```meson
201 fs.name('foo/bar/baz.dll.a') # baz.dll.a
202 ```
203
204 ### stem
205
206 *since 0.54.0*
207
208 Returns the last component of the path, dropping the last part of the
209 suffix
210
211 ```meson
212 fs.stem('foo/bar/baz.dll') # baz
213 fs.stem('foo/bar/baz.dll.a') # baz.dll
214 ```
215
216 ### read
217 - `read(path, encoding: 'utf-8')` *(since 0.57.0)*:
218 return a [string](Syntax.md#strings) with the contents of the given `path`.
219 If the `encoding` keyword argument is not specified, the file specified by
220 `path` is assumed to be utf-8 encoded. Binary files are not supported. The
221 provided paths should be relative to the current `meson.current_source_dir()`
222 or an absolute path outside the build directory is accepted. If the file
223 specified by `path` changes, this will trigger Meson to reconfigure the
224 project. If the file specified by `path` is a `files()` object it
225 cannot refer to a built file.
226
227 ### relative_to
228
229 *Since 1.3.0*
230
231 Return a relative filepath. In the event a relative path could not be found, the
232 absolute path of `to` is returned. Relative path arguments will be assumed to be
233 relative to `meson.current_source_dir()`.
234
235 Has the following positional arguments:
236 - to `str | file | custom_tgt | custom_idx | build_tgt`: end path
237 - from `str | file | custom_tgt | custom_idx | build_tgt`: start path
238
239 returns:
240 - a string
241
242 ### copyfile
243
244 *Since 0.64.0*
245
246 Copy a file from the source directory to the build directory at build time
247
248 Has the following positional arguments:
249 - src `File | str`: the file to copy
250
251 Has the following optional arguments:
252 - dest `str`: the name of the output file. If unset will be the basename of
253 the src argument
254
255 Has the following keyword arguments:
256 - install `bool`: Whether to install the copied file, defaults to false
257 - install_dir `str`: Where to install the file to
258 - install_tag: `str`: the install tag to assign to this target
259 - install_mode `array[str | int]`: the mode to install the file with
260
261 returns:
262 - a [[custom_target]] object
263
264 ```meson
265 copy = fs.copyfile('input-file', 'output-file')
266 ```