[Generator] Allow to have a way to attach to the generator. (#19565)

As soon as we moved to have a build of the generator that used dotnet we
opened the door to a number of developer life improvements. The very
first one of those is the poissibility to attach the dotnet debugger to
the bgen process and that way be able to debug.

In order to do that, this PR has changed two small things:

1. Added code in the main method of the generator that will block the
tool until a debugger is attached.
2. Changed the csproj to add the previously mentioned code only when the
enviroment variable XAMMACIOS_DEBUGGER is set. This way the code does
not reach our customers.

A README has been added explaining how to debug the processes via Visual
Studio. Any other IDE that support the dotnet debugger can be used this
way.

<img width="1075" alt="Screenshot 2023-12-03 at 19 10 18"
src="https://github.com/xamarin/xamarin-macios/assets/2190086/dbafc570-7c43-419f-977e-ace66f5561ac">

---------

Co-authored-by: Rolf Bjarne Kvinge <[email protected]>

src/bgen/BindingTouch.cs

@@ -41,6 +41,11 @@
 using Xamarin.Bundler;
 using Xamarin.Utils;
 
+#if NET && XAMMACIOS_DEBUGGER
+using System.Diagnostics;
+using System.Threading;
+#endif
+
 public class BindingTouch : IDisposable {
 #if NET
 	public static ApplePlatform [] AllPlatforms = new ApplePlatform [] { ApplePlatform.iOS, ApplePlatform.MacOSX, ApplePlatform.TVOS, ApplePlatform.MacCatalyst };
@@ -106,6 +111,19 @@ static void ShowHelp (OptionSet os)
 	public static int Main (string [] args)
 	{
 		try {
+#if NET && XAMMACIOS_DEBUGGER
+			// the following code will only be available for the macios
+			// developers to be able to debug the generator. This will
+			// block the generator until a debugger has attached to it
+			// our customers won't find any use for this.
+			var process = Process.GetCurrentProcess();
+			Console.WriteLine ($"Waiting for debugger to attach: ({ process.Id}) {process.ProcessName} { string.Join (" ", args)}");
+			while (!Debugger.IsAttached) {
+				Thread.Sleep (100);
+			}
+
+			Console.WriteLine ("Debugger attached");
+#endif
 			return Main2 (args);
 		} catch (Exception ex) {
 			ErrorHelper.Show (ex, false);

src/bgen/README.md

@@ -0,0 +1,30 @@
+## Debugging
+
+
+One of the main problems when adding changes to the generator was that before the generator was moved to dotnet, we could not attach the dotnet debugger to it. 
+Things have changed, and now if you want to debug the generator, you can do it with Visual Studio. To do so, you need to follow these steps:
+
+1. Export the environment variable `XAMMACIOS_DEBUGGER` with any value. For example:
+
+    ```bash
+    export XAMMACIOS_DEBUGGER=1
+    ```
+
+2. Open the src/src/bgen.csproj solution with Visual Studio.
+3. Add a break point at the end of the `Main` method in the BindingTouch.cs file.
+4. Rebuild the generator.
+
+
+Now, when the project is rebuilt you will have to pay attention to the output of the build. You will see something like this:
+
+```bash
+Waiting for debugger to attach: (55644) dotnet
+Waiting for debugger to attach: (55646) dotnet
+```
+
+These messages are telling you that the generator is waiting for the debugger to be attach to the process. To do so, you need to go to the Debug menu and select 
+the Attach to Process option. In the dialog that will appear, you will need to select the dotnet process that is running the generator. In this case, the process
+is the one with the PID 55644. Once you have selected the process, you can click on the Attach button.
+
+Because the generator is called several times, one per platform, you can attach to the different processes in case the issue you are trying to debug
+is platform specific.

src/bgen/bgen.csproj

@@ -5,6 +5,8 @@
     <TargetFramework>net$(BundledNETCoreAppTargetFrameworkVersion)</TargetFramework>
     <OutputType>Exe</OutputType>
     <DefineConstants>DEBUG;BGENERATOR;NET_4_0;NO_AUTHENTICODE;STATIC;NO_SYMBOL_WRITER;NET</DefineConstants>
+    <!-- help macios developers debug the generator during a build -->
+    <DefineConstants Condition="'$(XAMMACIOS_DEBUGGER)' != ''">$(DefineConstants);XAMMACIOS_DEBUGGER</DefineConstants>
     <WarningsAsErrors>Nullable</WarningsAsErrors>
     <Nullable>enable</Nullable>
   </PropertyGroup>