Node: doc: better document `--shared` build

[refack]

• Version: *
• Platform: *
• Subsystem: build,doc

./configure --shared / vcbuild shared should be better documented.

1. How to build
2. How to use
3. Support level

[addaleax]

If I may make the suggestion, we should also test it in some way if possible.

[refack]

If I may make the suggestion, we should also test it in some way if possible.

If we decide to support, maybe it should be deprecated?

[edit]
I'm just playing devil's advocate, it think it's an important meta-feature. But without CI testing it has rotted...
@Electron @nwjs @nodejs/electron-installer @nodejs/build

[gibfahn]

cc/ @mhdawson, @a-roberts (and maybe @sam-github) who were looking at this.

[mhdawson]

I've had it on our internal backlog to push this forward, we've just not gotten started on it yet. My starting goals are:

1) define set of tests to validate shared library works
2) add tests to ci, ideally in the regression runs
3) look at how we can better package/delivery, ideally as part of the binaries we already ship. Challenge on this front is not increasing the package size so we may need to look at moving to the node binary being a launcher that uses the shared library, this is what Java does.

[mhdawson]

And I'm firmly on the side that we need to improve not remove. It is used by electron and we also have internal products that need it.

[mhdawson]

The person(s) on our team who worked on this in the past have moved on to a different project. My next step is to schedule some handover with them but then it will still be a matter on finding time to move it forward.

[refack]

add tests to ci, ideally in the regression runs

https://github.com/nodejs/node/pull/13078 tried to get cctest to link against the shared lib. Could ideally become said launcher so we can run the JS suite against it.

[refack]

13078 tried to get cctest to link against the shared lib. Could ideally become said launcher so we can run the JS suite against it.

Alternatively create something like d8 that will both serve as a test harness and an embedding example.

[mhdawson]

@gibfahn can you post the launcher code that we already have for testing the shared library ? I've not had time to get back to this and it would at least be something we can discuss here in terms of moving forward on the testing.

[mhdawson]

Seein #15195 maybe we should add a job that simply compiles the shared library as a first step towards fully testing it.

[refack]

IMHO a job that just compiles for linux+Windows+macOS would be a great start

[mhdawson]

It should compile and build across all platforms so I don't think there is any reason to limit the target platforms.

[yhwang]

start to trace the current --shared and --enable-static options in configure and agreed with @refack about this:

IMHO a job that just compiles for linux+Windows+macOS would be a great start

and maybe both --shared and --enable-static need to be verified

[yhwang]

after studying the static/shared lib build process, my thinking is maybe we should build the static lib and use it to build the node executable. reason being are:

• directly integrate the static lib build with node executable
• node executable also use static lib and run test against node executable is also some sort of verification of static lib
• no performance impact of the node executable when using static lib. because there is still some performance impact when using shared lib

any thoughts?

[yhwang]

Create PR #17604 to refine the build procedure to:

1. build static lib and shared lib
2. use static lib to build executable by default
3. use shared lib to build executable when --shared is used.

Then the current CI will verify the static lib since the executable uses the static lib. One thing left is to create a new CI to verify the --shared build. I do see some test cases fail when using the shared lib to build the executable. We can fix them when the CI job is enabled.

[yhwang]

This is closed because my PR was landed and closed. However, there are still several things we need to do for this issue. We should reopen it.

[Trott]

What remains to be done here?

[jasnell]

This has not been updated in over a year and it's not clear what remaining actions there are. Closing but it can be reopened and I'm putting it on the Futures project board so it does not get lost.

[mhdawson]

@jasnell I think you failed to close so I'll do that. I still think we need a better defined API/documentation but I've not been able to line up people to work on it so I'll close for now.