Unsafe characters in file names redux

[Karl]

@compnerd

The problem is that in order to support DocC on Windows, we need to excise the preview server as the dependency on NIO is problematic as NIO does not currently support Windows.

This would be really nice to do anyway; NIO takes a long time to build (probably more than DocC itself).

It’s overkill for the preview server IMO.

[compnerd (Saleem Abdulrasool)]

@franklin

Gotcha. We could use a file-based HTTP server instead, e.g., python -m http.server, to get the website running locally on Windows.

Yeap, that was what I was doing to test the generated output from DocC on Windows and it was working well. Although it requires having python installed, you need that for debugging Swift code as LLDB depends on it, so its not too bad.

[ksluder (Kyle Sluder)]

It seems strange that a Swift tool would require a working Python installation to be functional. It brings all the Python-specific complexity of virtual environments and site-specific configuration into the Swift documentation workflow.

In my opinion, this is just further evidence that the design of DocC has made some very unfortunate dependency decisions on web technologies. If DocC had been designed to emit a plain bundle of HTML files like many documentation systems preceding it, there problems could all have been avoided.

[compnerd (Saleem Abdulrasool)]

@ksluder

It seems strange that a Swift tool would require a working Python installation to be functional. It brings all the Python-specific complexity of virtual environments and site-specific configuration into the Swift documentation workflow.

I think that this is misrepresenting the situation. The module http.server is part of the core Python distribution. LLDB already requires a working python installation to use the bindings for Swift. As a result, you already have all the necessary pieces installed on your host if you are debugging any Swift code. This is not really adding any complexity due to virtual environments. In fact, the complexity here is due to LLDB and not DocC - LLDB uses APIs that are not version agnostic, so it is tied to the specific version of Python it is built against.

[ksluder (Kyle Sluder)]

@compnerd

LLDB already requires a working python installation to use the bindings for Swift. As a result, you already have all the necessary pieces installed on your host if you are debugging any Swift code.

The Python that lldb invokes is not necessarily the same one that is invoked when you type python -m on the command line. For example, on macOS it is ideally invoking the one in the toolchain, falling back to the one provided by the OS. But a developer who also does Python development will have configured their PATH or aliases such that python invokes a version that they installed and have probably set up virtual environments within.

@compnerd

In fact, the complexity here is due to LLDB and not DocC - LLDB uses APIs that are not version agnostic, so it is tied to the specific version of Python it is built against.

Doesn’t this undermine the use of lldb as a good justification?

[compnerd (Saleem Abdulrasool)]

@ksluder

The Python that lldb invokes is not necessarily the same one that is invoked when you type python -m on the command line. For example, on macOS it is ideally invoking the one in the toolchain, falling back to the one provided by the OS. But a developer who also does Python development will have configured their PATH or aliases such that python invokes a version that they installed and have probably set up virtual environments within.

Particularly on Windows, this is equivalent to having changed DYLD_LIBRARY_PATH - at which point, you are responsible for both pieces. Path on Windows also serves as the library lookup order, and so, if you change that (directly or through venv) then that directly impacts the Python that LLDB uses. I'm not suggesting that this is ideal, but this is the current reality.

@ksluder

Doesn’t this undermine the use of lldb as a good justification?

Currently, LLDB is more or less required to properly debug Swift code. You are welcome to help improve the story with WinDBG, but, so far, LLDB has been the recommended way to debug, even on Windows, except in very certain circumstances.