-
Notifications
You must be signed in to change notification settings - Fork 7
/
Developer Notes.txt
157 lines (116 loc) · 6.48 KB
/
Developer Notes.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
Pinscape Config Tool - Notes for Developers
===========================================
1. Build system setup
To set up the build environment, you'll need:
* Microsoft Visual Studio. You can download the free Community
Edition from the Microsoft Web site. I don't think any special
install options are required. I'm currently building this
project with VS 2019. You can download the free Community
Edition here:
https://visualstudio.microsoft.com/
If you need an older version (VS 2017, VS 2015, etc), Microsoft makes
them available as well:
https://visualstudio.microsoft.com/vs/older-downloads/
If you want to create binary releases using the MakeRelease.bat
script, you'll also need a command-line ZIP tool. I use Info-ZIP
(infozip.sourceforge.net). You can *probably* use a different ZIP
tool if you prefer, as long as it has a command-line mode with its
primary command named ZIP.EXE, since most ZIP tools happen to use
similar command-line syntax. If you have any problems, though, you
might try installing Info-ZIP and seeing if that helps.
2. Building the program
Open the solution (.sln) file in Visual Studio. Go to the top
menu and select Build > Build Solution.
3. Visual Studio versions
As of this writing (7/2021), I'm building with Visual Studio 2019.
You can download it here:
https://visualstudio.microsoft.com/
VS 2019 is current as of this writing, but if the link above points to
something newer by the time you read this, you should be able to find
older releases here:
https://visualstudio.microsoft.com/vs/older-downloads/
You can also try building from a newer VS version if you prefer.
That's usually no problem with C# - Microsoft is pretty careful about
maintaining backwards compatibility so that existing programs continue
to build correctly. But if you do run into any weird compiler issues,
or the program doesn't function as expected once built, you should
probably stick with the same VS version I'm using. In the cases where
there are version incompatibilities across VS releases, it can be
tricky to figure out the right way to address them.
If you *do* do decide to try it with a newer VS version, you should be
able to simply open the solution (.sln) file without any changes.
However, VS sometimes requires a one-way format update to open an old
project in a new VS version, and this conversion will render the
solution (.sln) and/or project (.csproj) files incompatible with older
VS versions. If this type of one-way conversion is necessary, VS will
usually show you a warning message before making the change. If VS
shows such a warning when you open the project, CANCEL and use this
procedure instead:
- Whatever you do, DON'T migrate the ORIGINAL project/solution
files
- Instead, create COPIES of the project/solution files that need
to be converted
- Name the copies to indicate the new VS version they'll be used
with: e.g., copy PinscapeConfigTool.sln and name the copy to
signify the new VS year (e.g., PinscapeConfigTool-vs2023.sln)
- Open the NEW COPIES in the new VS, and allow VS to convert
those to the new format
- Use "git add" to add the new solution/project files to the
git repos
- If you have to make any project changes (e.g., adding new
source files to the project), please keep the ORIGINAL project/
solution files in sync with any project-level changes you have
to make, by manually back-porting the changes to the original
project/solution files. This is usually straightforward, since
the VS files in question are mostly XML, which makes them easy
easy to 'diff' and edit by hand.
If you run into the VS upgrade issue, and you're planning to make
changes that require adding new files to the build or otherwise
changing the project/solution trees, you might want to stop what
you're doing and either (a) go back to the VS version I'm using, so
that you don't have to do the conversion in the first place, or (b)
contact me before proceeding, to see if we can coordinate the VS
version migration on the mainline instead. Either way, you won't have
to deal with keeping two versions of the project files in sync.
That's tedious and error-prone.
My reason for keeping the project on the old VS version is NOT that
it's hard to do a version migration; it's that a migration can
destabilize the build in ways that aren't obvious. After a VS version
migration, it's important to do a full test of all features to make
sure that nothing in the program's run-time behavior changed or broke
due to the build process change. Staying on the same VS version gives
me more confidence that there won't be any new bugs or regressions
introduced by a small code change.
4. Config Tool HTML pages
The Config Tool uses an embedded HTML renderer control to display HTML
pages. Everything in the main window is displayed that way. The same
goes for the help system. Most of the other dialog windows use
Windows Forms (the C# dialog layout system) with native controls; it
should be obvious which windows are HTML and which are native by
looking at the [Design] mode of the form layouts for the various
window class .cs files.
For the HTML-based screens, the .htm source files and related
resources (.css, .js, .png, etc) are in the PinscapeConfigTool\html
subfolder.
5. Adding new HTML files and new HTML resources
If you want to add any new HTML pages, or new resources for the
HTML pages, such as new .png or .jpg images to show in the HTML
windows, follow this procedure:
- Create each new file in the PinscapeConfigTool\html folder
- Add the file to the git repository via "git add <file>" (git
has to be told explicitly that new files go in the repos; it
won't assume this on its own)
- Add the file to the Visual Studio project:
- Open the project in VS
- In the Solution Explorer pane, find PinscapeConfigTool > html
- Right click on the html folder and select Add > Existing Item
- Select the file(s) to add
- Click Add to accept the file selection
- The new files will now appear under the html folder in the tree;
for each one:
- Click on the file to select it into the Properties pane
- In the Properties pane, set the value of "Copy to Output
Directory" to "Copy if Newer"
Be sure to exit out of Visual Studio before committing the git
changes, to ensure that VS has finished writing out all changes to the
project files.