doc: add common issue regarding symbolic links on Windows

README.md

@@ -153,6 +153,14 @@
 
     这是因为源文件在导入时被直接链接或复制到了工程目录中，未触发 C++ Indexer 更新索引。此外，新版本的 Vitis 没有直接的命令或 UI 选项来重建或更新索引。最简单的解决方法是随意打开一个源文件，在任意行末输入一个空格并保存。IDE 会自动删除该空格，不会对源文件造成任何更改，但此操作可触发索引的自动更新。
 
+2. 在 Windows 上运行 `.bat` 构建脚本时可能会出现以下错误：
+
+    ```plaintext
+    Failed to create file symbolic link using mklink: 你没有足够的权限执行此操作。
+    ```
+
+    这是因为 `tcl` 在 Windows 上只能为文件夹创建符号链接，无法直接为文件创建链接。为文件创建符号链接需要使用 `mklink` 命令，该命令要求管理员权限。解决方法是以管理员身份运行 `.bat` 脚本。
+
 ## 待办事项
 
 - [x] 支持 Xilinx SDK 的 XSCT 接口
@@ -163,4 +171,4 @@
 
 ## 贡献指南
 
-如果您对该项目有任何改进意见或功能需求，欢迎提交 issue 或 pull request，commit 格式请参考 [Angular convention](https://github.com/conventional-changelog/commitlint/tree/master/@commitlint/config-conventional).
+如果您对该项目有任何改进意见或功能需求，欢迎提交 issue 或 pull request，commit 格式请参考 [Angular convention](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit).

platform/xilinx/setenv.bat

@@ -24,6 +24,8 @@ set /p "xilinx_path=Enter Xilinx installation path (press Enter for default: %de
 if "%xilinx_path%"=="" (
     set "xilinx_path=%default_path%"
 )
+REM Reset ERRORLEVEL to avoid false error codes
+verify > nul
 
 REM Convert version to integer
 for /f "tokens=1,2 delims=." %%a in ("%xilinx_version%") do (
@@ -35,10 +37,10 @@ set /a lowest_vitis_version=20192
 
 REM Determine the correct settings.bat path based on the Xilinx version and user path
 if %version_number% lss %lowest_vitis_version% (
-    echo Setting up environment for Xilinx SDK.
+    echo Setting up environment for Xilinx SDK %xilinx_version%.
     set settings_bat=%xilinx_path%\SDK\%xilinx_version%\settings64.bat
 ) else (
-    echo Setting up environment for Xilinx Vitis.
+    echo Setting up environment for Xilinx Vitis %xilinx_version%.
     set settings_bat=%xilinx_path%\Vitis\%xilinx_version%\settings64.bat
 )
 
@@ -52,7 +54,7 @@ if not exist "%settings_bat%" (
 REM Call the settings.bat file to set up the environment
 call "%settings_bat%"
 if "%ERRORLEVEL%" neq "0" (
-    echo Error: Failed to source "%settings_bat%".
+    echo Error: Failed to call "%settings_bat%"
     exit /b 1
 )
 

platform/xilinx/util.tcl

@@ -125,7 +125,21 @@ proc _handle_sources {app_name sources} {
             switch $link_srcs {
                 "y" {
                     # Create symbolic link
-                    file link -symbolic $target_path $eval_source
+                    # -- TCL cannont create symbolic link for files on Windows
+                    # -- Fallback to use mklink command
+                    if {$::tcl_platform(platform) eq "windows" && ![file isdirectory $eval_source]} {
+                        if {[catch {
+                            exec cmd /c mklink [file nativename $target_path] [file nativename $eval_source]
+                        } err]} {
+                            error "Failed to create file symbolic link using mklink: $err"
+                        }
+                    } else {
+                        if {[catch {
+                            file link -symbolic $target_path $eval_source
+                        } err]} {
+                            error "Failed to create symbolic link: $err"
+                        }
+                    }
                     _info "Created symbolic link: $target_path -> $eval_source"
                 }
                 "n" {

template.bat

@@ -6,7 +6,7 @@ set "config=%~dp0config.json"
 set "tools_dir=%~dp0scripts\platform\%platform%"
 
 REM Set up enviroment
-call "%tools_dir%\setenv_xilinx.bat" "%pltform_ver%"
+call "%tools_dir%\setenv.bat" "%pltform_ver%"
 if "%ERRORLEVEL%" neq "0" (
     echo Error: Failed to installize enviroment.
     pause >nul