Feature/include refactor (shader-slang#675)

* Refactor of path handling.
* Added PathInfo
* Changed ISlangFileSystem - such that has separate concepts of reading a file, getting a relative path and getting a canonical path
* Added support for getting a canonical path for windows/linux
* Made maps/testing around canonicalPaths
* User output remains around 'foundPath' - which is the same as before

* Small improvements around PathInfo
* Added a type and make constructors to make clear the different 'path' uses
* Fixed bug in findViewRecursively

* Checking and reporting for ignored #pragma once.

* Removed SLANG_PATH_TYPE_NONE as doesn't serve any useful purpose.

* Improve comments in slang.h aroung ISlangFileSystem

* Remove the need for <windows.h> in slang-io.cpp

* Ran premake5.

* Improvements and fixes around PathInfo.

* Fix typo on linix GetCanonical

* Make the ISlangFileSystem the same as before, and ISlangFileSystem contain the new methods.
Internally it always uses the ISlangFileSystemExt, and will wrap a ISlangFileSystem with WrapFileSystem, if it is determined (via queryInterface) that it doesn't implement the full interface.

Author: jsmall-zzz

slang.h

@@ -656,12 +656,16 @@ extern "C"
     Slang can make use of this interface whenever it would otherwise try to load files
     from disk, allowing applications to hook and/or override filesystem access from
     the compiler.
+
+    It is the responsibility of 
+    the caller of any method that returns a ISlangBlob to release the blob when it is no 
+    longer used (using 'release').
     */
+
     struct ISlangFileSystem : public ISlangUnknown
     {
     public:
         /** Load a file from `path` and return a blob of its contents
-
         @param path The path to load from, as a null-terminated UTF-8 string.
         @param outBlob A destination pointer to receive the blob of the file contents.
         @returns A `SlangResult` to indicate success or failure in loading the file.
@@ -673,10 +677,68 @@ extern "C"
         */
         virtual SLANG_NO_THROW SlangResult SLANG_MCALL loadFile(
             char const*     path,
-            ISlangBlob**    outBlob) = 0;
+            ISlangBlob** outBlob) = 0;
     };
     #define SLANG_UUID_ISlangFileSystem { 0x003A09FC, 0x3A4D, 0x4BA0, 0xAD, 0x60, 0x1F, 0xD8, 0x63, 0xA9, 0x15, 0xAB }
 
+    /* Type that identifies how a path should be interpreted */
+    typedef unsigned int SlangPathType;
+    enum
+    {
+        SLANG_PATH_TYPE_DIRECTORY,     /**< Path specified specifies a directory. */
+        SLANG_PATH_TYPE_FILE,           /**< Path specified is to a file. */
+    };
+
+    /** An extended file system abstraction.
+    
+    Implementing and using this interface over ISlangFileSystem gives much more control over how paths
+    are managed, as well as how it is determined if two files 'are the same'.
+
+    All paths as input char*, or output as ISlangBlobs are always encoded as UTF-8 strings.
+    Blobs that contain strings are always zero terminated.
+    */
+    struct ISlangFileSystemExt : public ISlangFileSystem
+    {
+    public:
+        /** Get a canonical path which uniquely identifies an object of the file system.
+           
+        Given a path, returns a 'canonical' path which will return the same path for the same file/directory. 
+        The canonical path is used to compare if two includes are the same file. 
+        The string for the canonical path is held zero terminated in the ISlangBlob of canonicalPathOut. 
+   
+        Note that a canonical path doesn't *have* to be a 'canonical' path, or a path at all
+        - it can just be a string that uniquely identifies a file. For example another possible mechanism
+        could be to store the filename combined with the file date time to uniquely identify it.
+     
+        The client must ensure the blob be released when no longer used, otherwise memory will leak.
+
+        @param path
+        @param canonicalPathOut
+        @returns A `SlangResult` to indicate success or failure getting the canonical path.
+        */
+        virtual SLANG_NO_THROW SlangResult SLANG_MCALL getCanoncialPath(
+            const char* path,
+            ISlangBlob** canonicalPathOut) = 0;
+
+        /** Get a path relative to a 'from' path.
+
+        The client must ensure the blob be released when no longer used, otherwise memory will leak.
+
+        @param fromPathType How to interpret the from path - as a file or a directory.
+        @param fromPath The from path. 
+        @param path Path to be determined relative to the fromPath
+        @param pathOut Holds the string which is the relative path. The string is held in the blob zero terminated.  
+        @returns A `SlangResult` to indicate success or failure in loading the file.
+        */
+        virtual SLANG_NO_THROW SlangResult SLANG_MCALL calcRelativePath(
+            SlangPathType fromPathType,
+            const char* fromPath,
+            const char* path,
+            ISlangBlob** pathOut) = 0;            
+    };
+
+    #define SLANG_UUID_ISlangFileSystemExt { 0x5fb632d2, 0x979d, 0x4481, { 0x9f, 0xee, 0x66, 0x3c, 0x3f, 0x14, 0x49, 0xe1 } }
+
     /*!
     @brief An instance of the Slang library.
     */

slang.sln

@@ -213,7 +213,7 @@
     <ClCompile Include="token-reader.cpp" />
   </ItemGroup>
   <ItemGroup>
-    <None Include="core.natvis" />
+    <Natvis Include="core.natvis" />
   </ItemGroup>
   <Import Project="$(VCTargetsPath)\Microsoft.Cpp.targets" />
   <ImportGroup Label="ExtensionTargets">

source/core/core.vcxproj

@@ -130,8 +130,8 @@
     </ClCompile>
   </ItemGroup>
   <ItemGroup>
-    <None Include="core.natvis">
+    <Natvis Include="core.natvis">
       <Filter>Source Files</Filter>
-    </None>
+    </Natvis>
   </ItemGroup>
 </Project>

source/core/core.vcxproj.filters

@@ -1,13 +1,20 @@
 #include "slang-io.h"
 #include "exception.h"
+
 #ifndef __STDC__
-#define __STDC__ 1
+#   define __STDC__ 1
 #endif
+
 #include <sys/stat.h>
+
 #ifdef _WIN32
-#include <direct.h>
+#   include <direct.h>
 #endif
 
+#include <limits.h> /* PATH_MAX */
+#include <stdio.h>
+#include <stdlib.h>
+
 namespace Slang
 {
 	bool File::Exists(const String & fileName)
@@ -125,6 +132,32 @@ namespace Slang
 #endif
 	}
 
+    /* static */SlangResult Path::GetCanonical(const String & path, String & canonicalPathOut)
+    {
+#if defined(_WIN32)
+        // https://msdn.microsoft.com/en-us/library/506720ff.aspx
+        wchar_t* absPath = ::_wfullpath(nullptr, path.ToWString(), 0);
+        if (!absPath)
+        {
+            return SLANG_FAIL;
+        }  
+
+        canonicalPathOut =  String::FromWString(absPath);
+        ::free(absPath);
+        return SLANG_OK;
+#else
+        // http://man7.org/linux/man-pages/man3/realpath.3.html
+        char* canonicalPath = ::realpath(path.begin(), nullptr);
+        if (canonicalPath)
+        {
+            canonicalPathOut = canonicalPath;
+            ::free(canonicalPath);
+            return SLANG_OK;
+        }
+        return SLANG_FAIL;
+#endif
+    }
+
 	Slang::String File::ReadAllText(const Slang::String & fileName)
 	{
 		StreamReader reader(new FileStream(fileName, FileMode::Open, FileAccess::Read, FileShare::ReadWrite));
@@ -152,4 +185,7 @@ namespace Slang
 		StreamWriter writer(new FileStream(fileName, FileMode::Create));
 		writer.Write(text);
 	}
+
+
 }
+

source/core/slang-io.cpp

@@ -31,6 +31,8 @@ namespace Slang
 		static String Combine(const String & path1, const String & path2);
 		static String Combine(const String & path1, const String & path2, const String & path3);
 		static bool CreateDir(const String & path);
+
+        static SlangResult GetCanonical(const String & path, String& canonicalPathOut);
 	};
 }
 

source/core/slang-io.h

@@ -186,7 +186,10 @@ namespace Slang
             for(auto sourceFile : translationUnit->sourceFiles)
             {
                 codeBuilder << "#line 1 \"";
-                for(auto c : sourceFile->path)
+
+                const String& path = sourceFile->pathInfo.foundPath;
+
+                for(auto c : path)
                 {
                     char buffer[] = { c, 0 };
                     switch(c)

source/slang/compiler.cpp

@@ -13,6 +13,7 @@
 
 namespace Slang
 {
+    struct PathInfo;
     struct IncludeHandler;
     class CompileRequest;
     class ProgramLayout;
@@ -395,6 +396,11 @@ namespace Slang
         ///
         ComPtr<ISlangFileSystem> fileSystem;
 
+        /// The extended file system implementation. Will be set to a default implementation
+        /// if fileSystem is nullptr. Otherwise it will either be fileSystem's interface, 
+        /// or a wrapped impl that makes fileSystem operate as fileSystemExt
+        ComPtr<ISlangFileSystemExt> fileSystemExt;
+
         /// Load a file into memory using the configured file system.
         ///
         /// @param path The path to attempt to load from
@@ -454,14 +460,14 @@ namespace Slang
 
         RefPtr<ModuleDecl> loadModule(
             Name*               name,
-            String const&       path,
-            ISlangBlob*         sourceBlob,
+            const PathInfo&     filePathInfo,
+            ISlangBlob*         fileContentsBlob,
             SourceLoc const& loc);
 
         void loadParsedModule(
             RefPtr<TranslationUnitRequest> const&   translationUnit,
             Name*                                   name,
-            String const&                           path);
+            PathInfo const&                         pathInfo);
 
         RefPtr<ModuleDecl> findOrImportModule(
             Name*               name,

source/slang/compiler.h

@@ -125,6 +125,8 @@ DIAGNOSTIC(-1, Note, seeOpeningToken, "see opening '$0'")
 DIAGNOSTIC(15300, Error, includeFailed, "failed to find include file '$0'")
 DIAGNOSTIC(15301, Error, importFailed, "failed to find imported file '$0'")
 DIAGNOSTIC(-1, Error, noIncludeHandlerSpecified, "no `#include` handler was specified")
+DIAGNOSTIC(15302, Error, noCanonicalPath, "`#include` handler didn't generate a canonical path for '$0'")
+
 
 // 154xx - macro definition
 DIAGNOSTIC(15400, Warning, macroRedefinition, "redefinition of macro '$0'")
@@ -138,6 +140,7 @@ DIAGNOSTIC(15501, Error, wrongNumberOfArgumentsToMacro, "wrong number of argumen
 // 156xx - pragmas
 DIAGNOSTIC(15600, Error, expectedPragmaDirectiveName, "expected a name after '#pragma'")
 DIAGNOSTIC(15601, Warning, unknownPragmaDirectiveIgnored, "ignoring unknown directive '#pragma $0'")
+DIAGNOSTIC(15602, Warning, pragmaOnceIgnored, "pragma once was ignored - this is typically because is not placed in an include")
 
 // 159xx - user-defined error/warning
 DIAGNOSTIC(15900, Error,    userDefinedError,   "#error: $0")

source/slang/diagnostic-defs.h

@@ -171,7 +171,7 @@ static void formatDiagnostic(
 
     auto humaneLoc = sourceManager->getHumaneLoc(diagnostic.loc);
 
-    sb << humaneLoc.path;
+    sb << humaneLoc.pathInfo.foundPath;
     sb << "(";
     sb << humaneLoc.line;
     sb << "): ";

source/slang/diagnostics.cpp

@@ -541,7 +541,7 @@ struct EmitVisitor
         emitRawText(buffer);
 
         // Only emit the path part of a `#line` directive if needed
-        if(sourceLocation.path != context->shared->loc.path)
+        if(sourceLocation.pathInfo.foundPath != context->shared->loc.pathInfo.foundPath)
         {
             emitRawText(" ");
 
@@ -578,7 +578,7 @@ struct EmitVisitor
 
             if(shouldUseGLSLStyleLineDirective)
             {
-                auto path = sourceLocation.path;
+                auto path = sourceLocation.pathInfo.foundPath;
 
                 // GLSL doesn't support the traditional form of a `#line` directive without
                 // an extension. Rather than depend on that extension we will output
@@ -609,7 +609,8 @@ struct EmitVisitor
                 // in a module that tracks source files.
 
                 emitRawText("\"");
-                for(auto c : sourceLocation.path)
+                const auto& path = sourceLocation.pathInfo.foundPath;
+                for(auto c : path)
                 {
                     char charBuffer[] = { c, 0 };
                     switch(c)
@@ -673,7 +674,7 @@ struct EmitVisitor
         // a differnet file or line, *or* if the source location is
         // somehow later on the line than what we want to emit,
         // then we need to emit a new `#line` directive.
-        if(sourceLocation.path != context->shared->loc.path
+        if(sourceLocation.pathInfo.foundPath != context->shared->loc.pathInfo.foundPath
             || sourceLocation.line != context->shared->loc.line
             || sourceLocation.column < context->shared->loc.column)
         {
@@ -682,7 +683,7 @@ struct EmitVisitor
             // to get us caught up.
             enum { kSmallLineCount = 3 };
             auto lineDiff = sourceLocation.line - context->shared->loc.line;
-            if(sourceLocation.path == context->shared->loc.path
+            if(sourceLocation.pathInfo.foundPath == context->shared->loc.pathInfo.foundPath
                 && sourceLocation.line > context->shared->loc.line
                 && lineDiff <= kSmallLineCount)
             {