Skip to content

Commit b19bdbf

Browse files
JDSherbertJDSherbert
authored
[Documentation] Vs - Include DLLs (#79)
[ADD] - Wrote the documentation with different methods of linking `dlls` within visual studio 2022 - Provided references and further reading at the bottom of the page. [ Remove] - Content about Static and dynamic linking, they will be in its own location later down the line, see some information in " programming handbook chat on discord " - Examples explaining use cases for dynamic linking and static..
2 parents 5e12366 + 9525262 commit b19bdbf

1 file changed

Lines changed: 213 additions & 0 deletions

File tree

‎docs/IDE/VisualStudio/IncludeDLLs.md‎

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
---
2+
layout: default
3+
title: Include DLLs
4+
nav_order: 2
5+
parent: Visual Studio
6+
grand_parent: IDE
7+
has_children: false
8+
---
9+
10+
{{ page.title }}
11+
======================
12+
13+
14+
This guide demonstrates how to include DLL files in a folder and seamlessly integrate them into the Debug or Build folder to generate a working build directory. It is particularly useful when dealing with libraries that require specific DLL files.
15+
16+
The following is based on an (IDE) [Visual Studio 2022](https://visualstudio.microsoft.com/vs/)
17+
18+
19+
### List of options:
20+
21+
<br>
22+
23+
1. ### **Root Directory Linking (Default):**
24+
25+
26+
Located in the same directory as `.vcxproj` known as `Root directory`.
27+
28+
Simply add the DLL into your project:
29+
30+
File structure (Root directory):
31+
32+
> Example.dll
33+
> main.cpp
34+
> Application.sln
35+
> Application.vcxproj
36+
> Application.vcxproj.user
37+
> Application.vcxproj.filters
38+
39+
40+
**Advantages:**
41+
42+
- Linking is done for the user by the (IDE).
43+
- Beneficial for small projects, where file management is not required.
44+
- The user does not have to worry about the (IDE) locating them, as long as they are listed within the root directory of the project.
45+
46+
**Cons:**
47+
48+
- Directory gets cluttered and harder to manage as the project grows in size.
49+
- Clutteres resource and collaboration effectivness.
50+
51+
<br>
52+
53+
2. ### **Working Directory Linking:**
54+
55+
Changing the working directory (Location of where the application starts the process of the build and runtime).
56+
57+
**Steps:**
58+
59+
* Open `Project Properties` (Right-click on the `Solution ` -> `Project Properties` in Visual Studio).
60+
* Navigate to `Configuration Properties` -> `Debugging` -> `Working Directory`.
61+
* Add the folder `(DLLs)` to specify that the project starts building from the `(DLLs)` folder instead of the root directory.
62+
63+
Running locally through (IDE) debugger:
64+
65+
- Has no requirements as long as the DLLs are located there when they are asked by the application.
66+
67+
Running from Output Directory:
68+
69+
- Requires the (DLL) directory to be built into the `output directory` for the `.exe` to locate it.
70+
71+
{: .note}
72+
See the bottom of the page to setup `Pre-linking Events`.
73+
74+
**Advantages:**
75+
76+
- Allows the user to define a costum (DLL) folder up in one directory of the (Root directory).
77+
- The project starts from the (DLL) folder.
78+
79+
**Cons:**
80+
81+
- Requires that the user builds the folder into `output directory` aiming to run it from an .exe
82+
- The user is limited to one folder of (DLLs), and can not define Debug from release versions.
83+
84+
<br>
85+
86+
3. #### **Defined locations (PATH):**
87+
88+
Giving the (IDE) or application a pre-defined location to look for dlls.
89+
90+
The following should be used if the aim is to specify multiple location or versions of dlls for the application.
91+
92+
**Steps:**
93+
94+
- Navigate to `Configuration Properties` -> `Debugging` -> `Environment`.
95+
- Specify a path as an example `PATH=$(ProjectDir)\DLLs`, where `(ProjectDir)` specifies the project root and `\DLLs` its folder.
96+
- This example the Working directory should be of `$(ProjectDir)` as listed in [Root Directory Linking (Default):](#root-directory-linking-default)
97+
98+
{: .note}
99+
Specify more than one path `PATH=$(ProjectDir)\DLLs, PATH=$(ProjectDir)\DLLs2` by the use of `,`.
100+
101+
{: .note}
102+
See the bottom of the page to setup Pre-linking Events.
103+
104+
**Advantages:**
105+
106+
- The user can define the locations of the `dlls`.
107+
- The user is not limited to changing the working directory.
108+
- The user can setup different `dlls` specific to debugging and release versions.
109+
- Project organization and file handling.
110+
111+
**Cons:**
112+
113+
- Requires that the user builds the folder into `output directory` aiming to run it from an .exe (If located in a folder).
114+
- Path has to be the same in `output directory` as in project files.
115+
- May become difficult to remember the setup and how to change the specifics.
116+
117+
118+
<br>
119+
120+
4. #### System directory linking:
121+
122+
{: .important}
123+
The following is specific to the users machine, which may affect the project for collaboration and future development if the `dlls` are not made accessible in the system globally or not installed. <br><br>
124+
Please use it with caution and existing knowledge as it requires `administrative privilages` and can potentionally lead to breaking your computer.
125+
126+
The following should be used if and when for example you are testing your environments and projects on a local server, where additionally adding `dlls` may become unfavored.
127+
128+
Remember the following should not be done for basic development environment!
129+
130+
- Most commonly the following is used by companies that are known, that automatically install new `dlls` into your system, such alike for example `nvidia graphics drivers` is being handled as the following must be accessible not only by the gpu, but also any potential video games.
131+
132+
**Steps:**
133+
134+
Access System Environment Variables:
135+
136+
1. Right-click on the Start button and select `System.`
137+
2. Click on `Advanced system settings` on the left.
138+
3. In the System Properties window, click the `Environment Variables` button.
139+
4. Modify System's PATH Variable:
140+
5. In the Environment Variables window, under the `System variables` section, find and select the `Path` variable.
141+
6. Click the `Edit` button.
142+
7. Add DLL Directory to PATH:
143+
8. In the Edit Environment Variable window, click `New` and paste the full path to the directory containing your DLL.
144+
9. Click `OK` to close each window.
145+
146+
{: .note}
147+
When completed make sure to restart the system and or any applications you may have open.
148+
149+
{: .note}
150+
If everything was done correctly, `visual studio` should now have access to globally linked dlls, this is because the search order of the (IDE) first takes through all of your `APIs`, `appplication`, `known dlls` and `dependencies`, if they aren ot found it looks for it through `system32` `path`, <br><br>
151+
Please see on further reading at the bottom of the page
152+
153+
**Advantages:**
154+
155+
- Makes your `dlls` accessible globally so that any project you make has access to them and avoid the setup each time.
156+
- You can rely on your own local `dlls` if not specified differently by the project.
157+
- One pre-defined location.
158+
159+
**Cons:**
160+
161+
- Can cause potential mishaps within the system due to defined `dlls`
162+
- The `dlls` are only accessible locally.
163+
- If the DLLs folder goes missing, every other project reliant on it breaks!
164+
- Might cause issues with `dll` version as project(s) may require different patches.
165+
166+
<br>
167+
168+
### **Pre-Linking Events**
169+
170+
1. **Building DLLs into output Directory:**
171+
- Navigate to Configuration Properties -> Build Events -> Pre-link Events.
172+
- Use the Copy function to move files from the "DLLs" folder to the build root.
173+
174+
2. **Add the Following Command:**
175+
176+
{: .code}
177+
```bash
178+
copy "$(ProjectDir)DLLs*.dll" "$(TargetDir)"
179+
ping -n 6 127.0.0.1 > nul
180+
```
181+
2.1 Notes for Expanding
182+
183+
- `copy` function to copy all DLL files `(*.dll)` from the "DLLs" folder in your project directory `($(ProjectDir))` to the target directory where the final build is stored `($(TargetDir))`
184+
- Adjust the file path according to the folder names based on Configuration steps 1 or 2.
185+
- `.dll` Specifies that all with an extentsion of it should be added to the build.
186+
187+
- Specify further `copy` in the next line, depending on the amount of DLL dependencies change the ping of `-n 6`
188+
- Alternativly the specification for specific `dll` can be called as such `copy "$(ProjectDir)DLLs\YourDLL1.dll" "$(TargetDir)"`, which instead using all in the directory calls the specified `.dll` file.
189+
190+
- ping -n 6 127.0.0.1 > nul
191+
- Used to add additionaly day to ensure, that the project has sufficient time to link and build "dynamic libraries " DLLs
192+
- `ping` command, essentially specifying a delay with amount.
193+
- `-n 6` by 6 seconds
194+
- `127.0.0.1 ` Loopback address, send loop to Address of 6 times with a delay of 6 seconds.
195+
- `> nul` Supresses output from the display (Directing the output to void)
196+
197+
198+
<br>
199+
200+
{: .further-reading}
201+
And Example for Path and working directory [DLL In Folder Example](https://github.com/VerzatileDevOrg/VS.DLLinFolder) <br>
202+
The following guide is based on an (IDE) [Visual Studio 2022](https://visualstudio.microsoft.com/vs/) <br>
203+
Visual studio [Build Events](https://learn.microsoft.com/en-us/visualstudio/ide/specifying-custom-build-events-in-visual-studio?view=vs-2022) <br> <br>
204+
Read about `Working directory` [Source Documentation by Microsoft " Dynamic link library search order. "](https://learn.microsoft.com/en-us/windows/win32/dlls/dynamic-link-library-search-order)<br><br>
205+
Read more about different types of Linking:<br>
206+
[Compile-Time Linking](https://learn.microsoft.com/en-us/cpp/cppcx/static-libraries-c-cx?view=msvc-170),
207+
[Runtime Linking](https://learn.microsoft.com/en-us/windows/win32/dlls/run-time-dynamic-linking)
208+
209+
210+
---
211+
212+
#### Author: VerzatileDev
213+
#### Published: 08/02/2024

0 commit comments

Comments
 (0)