[Kernel] explain usage of getenv "PWD" instead of getcwd

src/kernel_services/ast_queries/file.ml

@@ -530,6 +530,12 @@ let build_cpp_cmd = function
           if Sys.is_directory jcdb_path then jcdb_path
           else Filename.dirname jcdb_path
         in
+        (* TODO: we currently use PWD instead of Sys.getcwd () because OCaml has
+           no function in its stdlib to resolve symbolic links (e.g. realpath)
+           for a given path. 'getcwd' always resolves them, but if the user
+           supplies a path with symbolic links, this may cause issues.
+           Instead of forcing the user to always provide resolved paths, we
+           currently choose to never resolve them. *)
         let cwd = Unix.getenv "PWD" in
         if cwd <> dir then
           "cd " ^ dir ^ " && " ^ cpp_command

src/libraries/utils/filepath.ml

@@ -125,11 +125,12 @@ let insert base path_name =
       Array.set cache (hash land 255) (Some (path_name, path));
       path
 
-(* Note: we do not use `Sys.getcwd ()` because, if the current working
-   directory contains a symbolic link in its path, it will differ from
-   the one reported by getcwd. Since many path names come from the
-   command line, they are often provided with the symbolic name,
-   which leads to inconsistencies causing test oracles to differ. *)
+(* TODO: we currently use PWD instead of Sys.getcwd () because OCaml has
+   no function in its stdlib to resolve symbolic links (e.g. realpath)
+   for a given path. 'getcwd' always resolves them, but if the user
+   supplies a path with symbolic links, this may cause issues.
+   Instead of forcing the user to always provide resolved paths, we
+   currently choose to never resolve them. *)
 let cwd = insert dummy (Sys.getenv "PWD")
 
 type existence =

src/plugins/markdown-report/sarif_gen.ml

@@ -255,6 +255,13 @@ let gen_run remarks =
         (key, (dir :> string))
       ) (Filepath.all_symbolic_dirs ())
   in
+  (* TODO: we currently use Sys.getenv "PWD" instead of Sys.getcwd ()
+     because OCaml has no function in its stdlib to resolve symbolic links
+     (e.g. realpath) for a given path.
+     'getcwd' always resolves them, but if the user supplies a path with
+     symbolic links, this may cause issues.
+     Instead of forcing the user to always provide resolved paths, we
+     currently choose to never resolve them. *)
   let uriBases = ("PWD", Sys.getenv "PWD") :: symbolicDirs in
   let uriBasesJson =
     List.fold_left (fun acc (name, dir) ->

src/plugins/wp/wp_parameters.ml

@@ -1206,6 +1206,12 @@ let get_output_dir d =
 (* --- Session dir                                                        --- *)
 (* -------------------------------------------------------------------------- *)
 
+(* TODO: we currently use PWD instead of Sys.getcwd () because OCaml has
+   no function in its stdlib to resolve symbolic links (e.g. realpath)
+   for a given path. 'getcwd' always resolves them, but if the user
+   supplies a path with symbolic links, this may cause issues.
+   Instead of forcing the user to always provide resolved paths, we
+   currently choose to never resolve them. *)
 let default = Sys.getenv "PWD" ^ "/.frama-c"
 
 let has_session () =