improve compiler documentations

.vitepress/config.ts

@@ -21,7 +21,7 @@ export default defineConfig({
       { text: 'Manual', link: '/' },
       { text: 'Standard Library', link: '/standard-library/' },
     ],
-    
+
     sidebar: {
       '/': [
         {
@@ -51,6 +51,7 @@ export default defineConfig({
             { text: 'Compiler Options', link: '/compiler/compiler-options' },
             { text: 'Compiler Optimizations', link: '/compiler/compiler-optimizations' },
             { text: 'Cross Transpilation', link: '/compiler/cross-transpilation' },
+            { text: 'Backend', link: '/compiler/backend' },
             { text: 'Compiling', link: '/compiler/compiling' },
           ],
         },

src/compiler/backend.md

@@ -0,0 +1,51 @@
+# Backend
+
+Backend can mean many things. It can refer to the code generation or platform-dependent optimization phases of reference compiler. Alternatively, it can refer to the IR code or the process of compiling the IR code.
+
+## Backend Compiler
+
+Backend compiler refers to your compiler that you use to compile IR codes. This compiler can be an officially supported compiler, or it can be a 3rd party compiler you prefer to use.
+
+## Intermediate Representation (IR)
+
+Intermediate representation, aka IR, is a ready-to-compile representation that your compiler generates. This representation is a different form of the Jule source code you want to compile. It is mostly created for use by the backend-compiler for compilation.
+
+IR code can also be used to observe what code your compiler is generating. For example, the generated IR code may be different when some optimizations are on or off. IR representations can be useful to examine these differences.
+
+## C++ Backend Compilers
+
+JuleC commits that the codes it produces can be successfully compiled by the GNU Compiler Collection and Clang. Likewise, JuleC undertakes that the API it has and openly offers can be compiled with these compilers. While this preference is entirely left to the developers, JuleC has primarily embraced generating Clang compatible code, so it is recommended that Clang be the primary choice.
+
+Even if you can compile code generated outside of official support compilers with a different compiler, it is not under official support and there is no commitment that the code will be compiled. Regardless of whether you use Clang to compile the code or a compiler with or without official support, make sure that you either support or use a version of compiler that does support the C++ standard that Jule created.
+
+<strong>Officialy Supported Compilers</strong>
+
+- Clang
+- GNU Compiler Collection
+
+#### Clang on Windows
+
+The [MSVC](#msvc-compatibility) section mentions Jule's support for MSVC. You may want to use Clang on Windows. There is a Clang build we recommend so you can do this. It uses the MinGW toolchain. Compatible with compiling Jule IRs by default.
+
+Here is the recommended [LLVM/Clang/LLD based mingw-w64 toolchain](https://github.com/mstorsjo/llvm-mingw) repository on GitHub.
+
+### C++ Standards
+
+Jule aims to generate code in accordance with the most ideal C++ standard supported by the C++ compilers it offers official support, and is committed to compiling it with compilers that fully comply with this standard. As a result of our tests, the most suitable standard seems to be C++14. The C++14 standard has full support on officially supported compilers and is the default compilation standard. For this reason, Jule aims to produce code in accordance with the C++14 standard.
+
+When we tested it, Clang successfully compiled the API and a simple code output in the C++17 and C++20 standard. However, when we tested with GCC, we encountered compiler errors in the C++20 standard with the same parameters.
+
+These tests were performed on Linux. When we tested GCC compilation on Windows with MinGW, we encountered different results. If you're working on a cross-platform project and your code must be compilable on supported operating systems, consider platform-dependent differences if you're trying to compile with a standard other than the officially supported C++ standard.
+
+### MSVC Compatibility
+
+Jule does not support MSVC. This is why you won't have an official MSVC support. We ran into issues when we tried IR's support of MSVC experimentally. Our standard libraries such as `std::sys` contain code that is not compatible with MSVC. We had a problem when we tried to compile JuleC IR with MSVC Clang. So even if you want to do that, you're probably going to have to put effort into MSVC.
+
+### GCC Problems
+
+GCC can sometimes document an error like `File too big` when compiling IR codes. We encountered this while compiling the JuleC IR when we tried to build a CI on GitHub Actions. We solved this by adding `-Wa,-mbig-obj` to the compile command.
+
+Our command looked like this:
+```
+g++ -Wa,-mbig-obj -O0 --std=c++17 -w -o .\bin\julec.exe .\ir.cpp
+```

src/compiler/compiling.md

@@ -1,6 +1,6 @@
 # Compiling
 
-## Using JuleC
+## Using JuleC (Reference Compiler)
 Let's start with a simple hello world program and learn compiling from this program.
 
 We have a `main.jule` file:
@@ -21,6 +21,25 @@ In compile mode, JuleC will show you the build command itself on the command lin
 
 As result we have a executable machine code result of our program.
 
+### Backend Compiler Optimizations
+
+By default, JuleC sets your backend compiler's optimizations to the lowest possible level and compiles your code as such. These optimizations are independent of the compiler optimizations that JuleC has, they are the backend-compiler optimizations you use for IR compilation. The created executable file is available for debugging. The lowest optimization level usually allows the backend-compiler to exhibit the fastest compilation performance. But without the generated executable optimizations it can be significantly underperforming.
+
+If you want to compile your code with backend-compiler optimizations, there are several ways you can do it.
+
+#### Set Backend Compiler Optimizations via `pass` Directive
+
+You can add the `pass` directive to a suitable place in the main package of your program and adjust the optimizations of your backend-compiler. This method works most of the time.
+
+For example to enable Clang's `O3` optimizations:
+```
+//jule:pass -O3
+```
+
+#### Transpile and Compile Manually
+
+You can transpile your code and compile your IR code with your desired optimization setting by customizing the suggested compile command by compiler or with a completely custom compile command.
+
 ### Transpilation
 
 Preferably, instead of compiling your code directly, you may want to transpile your code for various reasons to obtain the IR code. This scenario is mostly used when you want to distribute IR code, modify it, debug compiler's code generation, compile with different compilers or compilation commands.
@@ -37,20 +56,11 @@ In Jule, each program is also a package. Jule source codes in the directory are
 
 This also eliminates the need to link individual source codes to the compiler and significantly avoids the occurrence of long compiler commands. It makes it easy to understand which of the source codes are in the main program, the answer is simple: all the Jule source codes in the directory. Because of this approach, each Jule program is kept in a separate directory as a package, causing optimistic pressure on the project organization. 
 
-## Compiler and C++ Standard Support
-JuleC commits that the codes it produces can be successfully compiled by the GNU Compiler Collection and Clang. Likewise, JuleC undertakes that the API it has and openly offers can be compiled with these compilers. While this preference is entirely left to the developers, JuleC has primarily embraced generating Clang compatible code, so it is recommended that Clang be the primary choice.
-
-Even if you can compile code generated outside of official support compilers with a different compiler, it is not under official support and there is no commitment that the code will be compiled. Regardless of whether you use Clang to compile the code or a compiler with or without official support, make sure that you either support or use a version of compiler that does support the C++ standard that Jule created.
-
-Jule aims to generate code in accordance with the most ideal C++ standard supported by the C++ compilers it offers official support, and is committed to compiling it with compilers that fully comply with this standard. As a result of our tests, the most suitable standard seems to be C++14. The C++14 standard has full support on officially supported compilers and is the default compilation standard. For this reason, Jule aims to produce code in accordance with the C++14 standard.
-
-When we tested it, Clang successfully compiled the API and a simple code output in the C++17 and C++20 standard. However, when we tested with GCC, we encountered compiler errors in the C++20 standard with the same parameters.
-
-These tests were performed on Linux. When we tested GCC compilation on Windows with MinGW, we encountered different results. If you're working on a cross-platform project and your code must be compilable on supported operating systems, consider platform-dependent differences if you're trying to compile with a standard other than the officially supported C++ standard.
-
-## Using C++ Compiler
+## Using Backend Compiler
 JuleC has multiple officially supported C++ compilers. For this reason, it does not contain a specific C++ compiler in itself to keep your download sizes small and leave the choice to you. If you're using Linux or a similar operating system, you can usually already have an officially supported C++ compiler. Once you've decided on the C++ compiler you want to use, JuleC can take care of the rest for you. Before that, you need to give JuleC a few simple instructions.
 
 JuleC will automatically choose the recommended C++ compiler when compiling your code. If the recommended compiler is your preferred compiler, you don't need to take an action. But if not, you need to set your compiler using the related compiler option(s).
 
 If you need a special configuration for your build, it is recommended to create a script file for it or write compile command in a document such as a readme files. This makes it clearer and easier how to compile the project, as well as a faster and more comfortable development experience.
+
+Please read [backend](/compiler/backend) documentations for more information about supported C++ compilers and standards.