[libvirt] [PATCH] RFC: maint: Sort public symbols within a release

In libvirt_private.syms, we have a policy of keeping blocks of symbols sorted by name - in fact, we enforce it during 'make check' with our check-symsorting rule calling out to a perl script. But libvirt_public.syms has been more cavalier over the years. 21 releases have been trivially sorted due to adding only one symbol; while the following 27 releases listed multiple symbols in alphabetical order, even if the symbols were not chronologically added in that order [1]: 0.0.3 0.9.5 1.1.0 0.3.0 0.9.7 1.1.1 0.3.3 0.9.8 1.2.5 0.4.2 0.9.9 1.2.8 0.6.3 0.9.10 1.2.11 0.7.5 0.9.13 1.2.15 0.9.0 1.0.1 1.3.3 0.9.2 1.0.2 3.1.0 0.9.3 1.0.3 3.4.0 [1] Case study: git log -p v0.9.9..v0.9.10 src/libvirt_public.syms shows 9 commits adding 9 APIs among 7 authors: 0b7ddf9e - trivially in order adb99a05 - appending happened to also be sorted order 1f7aa0ac - irrelevant (removing TABs, not adding symbol) 6714fd04 - added in sorted order 8f8b0802 - appended, out of order e1eea747 - re-sorted previous addition, and added in sorted order 02af3e13 - added in sorted order c471e55e - added in sorted order 99fd69c3 - added in sorted order The following patch changes the remaining 37 releases to do likewise, and documents the practice. Signed-off-by: Eric Blake <eblake(a)redhat.com&gt; --- I'm not sure if we want this patch - it got much bigger than I was expecting. 37 releases is less than half of the total versions in the file, but larger than the number of releases that were sorted (where it is not even obvious if that was always intentional or by luck). We could also decide to adopt a policy of listing symbols in the same order as remote_protocol.x (although not all symbols go over RPC), but that seems like it would be even more churn and harder to enforce. Ideally, if we DO want this patch, we should also teach 'make check' via src/check-symsorting.pl how to enforce it on the public file; as I did not do that, this is marked RFC. The diffstat shows a delta because I deleted 5 blank lines and added 2 comment lines. --- src/libvirt_public.syms | 313 ++++++++++++++++++++-------------------- 1 file changed, 155 insertions(+), 158 deletions(-) diff --git a/src/libvirt_public.syms b/src/libvirt_public.syms index 75f7fdfb0c..f9e0072352 100644 --- a/src/libvirt_public.syms +++ b/src/libvirt_public.syms @@ -10,6 +10,8 @@ # soname version info can't enforce this since we never # change the soname # +# Keep this file sorted by version, then by symbols within each version. +# LIBVIRT_0.0.3 { global: virConnectClose; @@ -43,44 +45,43 @@ LIBVIRT_0.0.3 { LIBVIRT_0.0.5 { global: - virDomainLookupByUUID; virDomainGetUUID; + virDomainLookupByUUID; } LIBVIRT_0.0.3; LIBVIRT_0.1.0 { global: + virConnCopyLastError; + virConnGetLastError; + virConnResetLastError; + virConnSetErrorFunc; + virCopyLastError; + virDefaultErrorFunc; + virDomainReboot; + virGetLastError; virInitialize; virNodeGetInfo; - virDomainReboot; - - virCopyLastError; - virConnSetErrorFunc; - virResetLastError; virResetError; - virConnGetLastError; - virGetLastError; + virResetLastError; virSetErrorFunc; - virConnCopyLastError; - virConnResetLastError; - virDefaultErrorFunc; } LIBVIRT_0.0.5; LIBVIRT_0.1.1 { global: - virDomainLookupByUUIDString; + virConnectListDefinedDomains; + virDomainCreate; + virDomainDefineXML; virDomainGetUUIDString; + virDomainLookupByUUIDString; virDomainSetMemory; - virDomainDefineXML; - virDomainCreate; virDomainUndefine; - virConnectListDefinedDomains; } LIBVIRT_0.1.0; LIBVIRT_0.1.4 { global: - virDomainSetVcpus; - virDomainPinVcpu; virDomainGetVcpus; + virDomainPinVcpu; + virDomainSetVcpus; } LIBVIRT_0.1.1; LIBVIRT_0.1.5 { @@ -90,39 +91,39 @@ LIBVIRT_0.1.5 { LIBVIRT_0.1.9 { global: - virDomainCoreDump; virDomainAttachDevice; + virDomainCoreDump; virDomainDetachDevice; } LIBVIRT_0.1.5; LIBVIRT_0.2.0 { global: - virConnectNumOfNetworks; + virConnectListDefinedNetworks; virConnectListNetworks; virConnectNumOfDefinedNetworks; - virConnectListDefinedNetworks; - virNetworkLookupByName; - virNetworkLookupByUUID; - virNetworkLookupByUUIDString; + virConnectNumOfNetworks; + virNetworkCreate; virNetworkCreateXML; virNetworkDefineXML; - virNetworkUndefine; - virNetworkCreate; virNetworkDestroy; virNetworkFree; + virNetworkGetBridgeName; virNetworkGetName; virNetworkGetUUID; virNetworkGetUUIDString; virNetworkGetXMLDesc; - virNetworkGetBridgeName; + virNetworkLookupByName; + virNetworkLookupByUUID; + virNetworkLookupByUUIDString; + virNetworkUndefine; } LIBVIRT_0.1.9; LIBVIRT_0.2.1 { global: virConnectGetCapabilities; virConnectGetMaxVcpus; - virDomainGetMaxVcpus; virDomainGetAutostart; + virDomainGetMaxVcpus; virDomainSetAutostart; virNetworkGetAutostart; virNetworkSetAutostart; @@ -130,8 +131,8 @@ LIBVIRT_0.2.1 { LIBVIRT_0.2.3 { global: - virDomainGetSchedulerType; virDomainGetSchedulerParameters; + virDomainGetSchedulerType; virDomainSetSchedulerParameters; } LIBVIRT_0.2.1; @@ -145,9 +146,9 @@ LIBVIRT_0.3.0 { LIBVIRT_0.3.2 { global: - virDomainMigrate; virDomainBlockStats; virDomainInterfaceStats; + virDomainMigrate; } LIBVIRT_0.3.0; LIBVIRT_0.3.3 { @@ -158,52 +159,51 @@ LIBVIRT_0.3.3 { LIBVIRT_0.4.0 { global: - virConnectOpenAuth; virConnectAuthPtrDefault; + virConnectOpenAuth; } LIBVIRT_0.3.3; LIBVIRT_0.4.1 { global: - virStoragePoolGetConnect; - virConnectNumOfStoragePools; - virConnectNumOfDefinedStoragePools; - virConnectListStoragePools; virConnectListDefinedStoragePools; - virStoragePoolLookupByName; - virStoragePoolLookupByUUID; - virStoragePoolLookupByUUIDString; - virStoragePoolLookupByVolume; + virConnectListStoragePools; + virConnectNumOfDefinedStoragePools; + virConnectNumOfStoragePools; + virStoragePoolBuild; + virStoragePoolCreate; virStoragePoolCreateXML; virStoragePoolDefineXML; - virStoragePoolUndefine; - virStoragePoolCreate; - virStoragePoolBuild; - virStoragePoolDestroy; virStoragePoolDelete; - virStoragePoolRefresh; + virStoragePoolDestroy; virStoragePoolFree; + virStoragePoolGetAutostart; + virStoragePoolGetConnect; + virStoragePoolGetInfo; virStoragePoolGetName; virStoragePoolGetUUID; virStoragePoolGetUUIDString; - virStoragePoolGetInfo; virStoragePoolGetXMLDesc; - virStoragePoolSetAutostart; - virStoragePoolGetAutostart; - virStoragePoolNumOfVolumes; virStoragePoolListVolumes; - - virStorageVolGetConnect; - virStorageVolLookupByName; - virStorageVolLookupByKey; - virStorageVolLookupByPath; + virStoragePoolLookupByName; + virStoragePoolLookupByUUID; + virStoragePoolLookupByUUIDString; + virStoragePoolLookupByVolume; + virStoragePoolNumOfVolumes; + virStoragePoolRefresh; + virStoragePoolSetAutostart; + virStoragePoolUndefine; virStorageVolCreateXML; virStorageVolDelete; virStorageVolFree; - virStorageVolGetName; - virStorageVolGetKey; + virStorageVolGetConnect; virStorageVolGetInfo; - virStorageVolGetXMLDesc; + virStorageVolGetKey; + virStorageVolGetName; virStorageVolGetPath; + virStorageVolGetXMLDesc; + virStorageVolLookupByKey; + virStorageVolLookupByName; + virStorageVolLookupByPath; } LIBVIRT_0.4.0; LIBVIRT_0.4.2 { @@ -219,21 +219,19 @@ LIBVIRT_0.4.5 { LIBVIRT_0.5.0 { global: + virConnectDomainEventDeregister; + virConnectDomainEventRegister; virDomainCreateXML; virEventRegisterImpl; - virConnectDomainEventRegister; - virConnectDomainEventDeregister; - - virNodeNumOfDevices; - virNodeListDevices; - virNodeDeviceLookupByName; virNodeDeviceFree; - virNodeDeviceGetXMLDesc; virNodeDeviceGetName; virNodeDeviceGetParent; - virNodeDeviceNumOfCaps; + virNodeDeviceGetXMLDesc; virNodeDeviceListCaps; - + virNodeDeviceLookupByName; + virNodeDeviceNumOfCaps; + virNodeListDevices; + virNodeNumOfDevices; } LIBVIRT_0.4.5; LIBVIRT_0.6.0 { @@ -241,21 +239,20 @@ LIBVIRT_0.6.0 { virConnectRef; virDomainRef; virNetworkRef; + virNodeDeviceRef; virStoragePoolRef; virStorageVolRef; - virNodeDeviceRef; - } LIBVIRT_0.5.0; LIBVIRT_0.6.1 { global: + virDomainGetSecurityLabel; virFreeError; - virSaveLastError; virNodeDeviceDettach; virNodeDeviceReAttach; virNodeDeviceReset; - virDomainGetSecurityLabel; virNodeGetSecurityModel; + virSaveLastError; } LIBVIRT_0.6.0; LIBVIRT_0.6.3 { @@ -266,67 +263,67 @@ LIBVIRT_0.6.3 { LIBVIRT_0.6.4 { global: - virInterfaceGetConnect; - virConnectNumOfInterfaces; + virConnectDomainXMLFromNative; + virConnectDomainXMLToNative; virConnectListInterfaces; - virInterfaceLookupByName; - virInterfaceLookupByMACString; - virInterfaceGetName; + virConnectNumOfInterfaces; + virInterfaceCreate; + virInterfaceDefineXML; + virInterfaceDestroy; + virInterfaceFree; + virInterfaceGetConnect; virInterfaceGetMACString; + virInterfaceGetName; virInterfaceGetXMLDesc; + virInterfaceLookupByMACString; + virInterfaceLookupByName; virInterfaceRef; - virInterfaceFree; - virInterfaceDefineXML; virInterfaceUndefine; - virInterfaceCreate; - virInterfaceDestroy; virStorageVolCreateXMLFrom; - virConnectDomainXMLFromNative; - virConnectDomainXMLToNative; } LIBVIRT_0.6.3; LIBVIRT_0.7.0 { global: - virConnectNumOfDefinedInterfaces; virConnectListDefinedInterfaces; + virConnectNumOfDefinedInterfaces; } LIBVIRT_0.6.4; LIBVIRT_0.7.1 { global: - virSecretGetConnect; - virConnectNumOfSecrets; virConnectListSecrets; - virSecretLookupByUUID; - virSecretLookupByUUIDString; - virSecretLookupByUsage; + virConnectNumOfSecrets; virSecretDefineXML; + virSecretFree; + virSecretGetConnect; virSecretGetUUID; virSecretGetUUIDString; - virSecretGetUsageType; virSecretGetUsageID; + virSecretGetUsageType; + virSecretGetValue; virSecretGetXMLDesc; + virSecretLookupByUUID; + virSecretLookupByUUIDString; + virSecretLookupByUsage; + virSecretRef; virSecretSetValue; - virSecretGetValue; virSecretUndefine; - virSecretRef; - virSecretFree; } LIBVIRT_0.7.0; LIBVIRT_0.7.2 { global: - virStreamNew; - virStreamRef; - virStreamSend; - virStreamRecv; - virStreamSendAll; - virStreamRecvAll; + virDomainMigrateToURI; + virStreamAbort; virStreamEventAddCallback; - virStreamEventUpdateCallback; virStreamEventRemoveCallback; + virStreamEventUpdateCallback; virStreamFinish; - virStreamAbort; virStreamFree; - virDomainMigrateToURI; + virStreamNew; + virStreamRecv; + virStreamRecvAll; + virStreamRef; + virStreamSend; + virStreamSendAll; } LIBVIRT_0.7.1; LIBVIRT_0.7.3 { @@ -336,11 +333,11 @@ LIBVIRT_0.7.3 { virConnectIsSecure; virDomainIsActive; virDomainIsPersistent; + virInterfaceIsActive; virNetworkIsActive; virNetworkIsPersistent; virStoragePoolIsActive; virStoragePoolIsPersistent; - virInterfaceIsActive; } LIBVIRT_0.7.2; LIBVIRT_0.7.5 { @@ -351,46 +348,46 @@ LIBVIRT_0.7.5 { LIBVIRT_0.7.7 { global: + virConnectBaselineCPU; + virDomainAbortJob; virDomainAttachDeviceFlags; virDomainDetachDeviceFlags; - virConnectBaselineCPU; virDomainGetJobInfo; - virDomainAbortJob; } LIBVIRT_0.7.5; LIBVIRT_0.8.0 { global: - virStorageVolWipe; - virDomainMigrateSetMaxDowntime; - virConnectDomainEventRegisterAny; virConnectDomainEventDeregisterAny; - virDomainUpdateDeviceFlags; + virConnectDomainEventRegisterAny; virConnectListNWFilters; virConnectNumOfNWFilters; - virNWFilterLookupByName; - virNWFilterLookupByUUID; - virNWFilterLookupByUUIDString; + virDomainHasCurrentSnapshot; + virDomainHasManagedSaveImage; + virDomainManagedSave; + virDomainManagedSaveRemove; + virDomainMigrateSetMaxDowntime; + virDomainRevertToSnapshot; + virDomainSnapshotCreateXML; + virDomainSnapshotCurrent; + virDomainSnapshotDelete; + virDomainSnapshotFree; + virDomainSnapshotGetXMLDesc; + virDomainSnapshotListNames; + virDomainSnapshotLookupByName; + virDomainSnapshotNum; + virDomainUpdateDeviceFlags; + virNWFilterDefineXML; virNWFilterFree; virNWFilterGetName; virNWFilterGetUUID; virNWFilterGetUUIDString; virNWFilterGetXMLDesc; + virNWFilterLookupByName; + virNWFilterLookupByUUID; + virNWFilterLookupByUUIDString; virNWFilterRef; - virNWFilterDefineXML; virNWFilterUndefine; - virDomainManagedSave; - virDomainHasManagedSaveImage; - virDomainManagedSaveRemove; - virDomainSnapshotCreateXML; - virDomainSnapshotGetXMLDesc; - virDomainSnapshotNum; - virDomainSnapshotListNames; - virDomainSnapshotLookupByName; - virDomainHasCurrentSnapshot; - virDomainSnapshotCurrent; - virDomainRevertToSnapshot; - virDomainSnapshotDelete; - virDomainSnapshotFree; + virStorageVolWipe; } LIBVIRT_0.7.7; @@ -407,16 +404,16 @@ LIBVIRT_0.8.2 { LIBVIRT_0.8.5 { global: - virDomainSetMemoryParameters; virDomainGetMemoryParameters; virDomainGetVcpusFlags; + virDomainSetMemoryParameters; virDomainSetVcpusFlags; } LIBVIRT_0.8.2; LIBVIRT_0.8.6 { global: - virDomainOpenConsole; virDomainIsUpdated; + virDomainOpenConsole; } LIBVIRT_0.8.5; LIBVIRT_0.8.8 { @@ -468,16 +465,16 @@ LIBVIRT_0.9.3 { LIBVIRT_0.9.4 { global: + virDomainBlockJobAbort; + virDomainBlockJobSetSpeed; + virDomainBlockPull; + virDomainDestroyFlags; + virDomainGetBlockJobInfo; virDomainRestoreFlags; virDomainSaveFlags; virDomainSaveImageDefineXML; virDomainSaveImageGetXMLDesc; virDomainUndefineFlags; - virDomainDestroyFlags; - virDomainBlockJobAbort; - virDomainGetBlockJobInfo; - virDomainBlockJobSetSpeed; - virDomainBlockPull; } LIBVIRT_0.9.3; LIBVIRT_0.9.5 { @@ -546,20 +543,20 @@ LIBVIRT_0.9.13 { LIBVIRT_0.10.0 { global: - virDomainGetHostname; virConnectRegisterCloseCallback; virConnectUnregisterCloseCallback; + virDomainGetEmulatorPinInfo; + virDomainGetHostname; virDomainGetSecurityLabelList; virDomainPinEmulator; - virDomainGetEmulatorPinInfo; } LIBVIRT_0.9.13; LIBVIRT_0.10.2 { global: virConnectListAllInterfaces; + virConnectListAllNWFilters; virConnectListAllNetworks; virConnectListAllNodeDevices; - virConnectListAllNWFilters; virConnectListAllSecrets; virConnectListAllStoragePools; virDomainBlockCommit; @@ -641,8 +638,8 @@ LIBVIRT_1.1.3 { LIBVIRT_1.2.1 { global: - virConnectNetworkEventRegisterAny; virConnectNetworkEventDeregisterAny; + virConnectNetworkEventRegisterAny; } LIBVIRT_1.1.3; LIBVIRT_1.2.3 { @@ -660,9 +657,9 @@ LIBVIRT_1.2.5 { LIBVIRT_1.2.6 { global: - virNodeGetFreePages; virNetworkDHCPLeaseFree; virNetworkGetDHCPLeases; + virNodeGetFreePages; } LIBVIRT_1.2.5; LIBVIRT_1.2.7 { @@ -697,11 +694,11 @@ LIBVIRT_1.2.12 { LIBVIRT_1.2.14 { global: - virDomainIOThreadInfoFree; virDomainGetIOThreadInfo; - virDomainPinIOThread; + virDomainIOThreadInfoFree; virDomainInterfaceAddresses; virDomainInterfaceFree; + virDomainPinIOThread; } LIBVIRT_1.2.12; LIBVIRT_1.2.15 { @@ -727,30 +724,30 @@ LIBVIRT_1.2.19 { LIBVIRT_1.3.3 { global: - virDomainMigrateStartPostCopy; virDomainGetPerfEvents; + virDomainMigrateStartPostCopy; virDomainSetPerfEvents; } LIBVIRT_1.2.19; LIBVIRT_2.0.0 { global: - virConnectStoragePoolEventRegisterAny; virConnectStoragePoolEventDeregisterAny; + virConnectStoragePoolEventRegisterAny; virDomainGetGuestVcpus; virDomainSetGuestVcpus; } LIBVIRT_1.3.3; LIBVIRT_2.2.0 { global: - virConnectNodeDeviceEventRegisterAny; virConnectNodeDeviceEventDeregisterAny; + virConnectNodeDeviceEventRegisterAny; } LIBVIRT_2.0.0; LIBVIRT_3.0.0 { global: - virStorageVolGetInfoFlags; - virConnectSecretEventRegisterAny; virConnectSecretEventDeregisterAny; + virConnectSecretEventRegisterAny; + virStorageVolGetInfoFlags; } LIBVIRT_2.2.0; LIBVIRT_3.1.0 { @@ -770,9 +767,9 @@ LIBVIRT_3.4.0 { LIBVIRT_3.7.0 { global: - virDomainMigrateGetMaxDowntime; - virDomainManagedSaveGetXMLDesc; virDomainManagedSaveDefineXML; + virDomainManagedSaveGetXMLDesc; + virDomainMigrateGetMaxDowntime; } LIBVIRT_3.4.0; LIBVIRT_3.9.0 { @@ -787,26 +784,26 @@ LIBVIRT_4.1.0 { LIBVIRT_4.4.0 { global: - virDomainDetachDeviceAlias; - virConnectCompareHypervisorCPU; virConnectBaselineHypervisorCPU; + virConnectCompareHypervisorCPU; + virDomainDetachDeviceAlias; } LIBVIRT_4.1.0; LIBVIRT_4.5.0 { global: + virConnectListAllNWFilterBindings; + virDomainGetLaunchSecurityInfo; virGetLastErrorCode; virGetLastErrorDomain; - virNodeGetSEVInfo; - virDomainGetLaunchSecurityInfo; - virNWFilterBindingLookupByPortDev; - virConnectListAllNWFilterBindings; virNWFilterBindingCreateXML; - virNWFilterBindingGetXMLDesc; virNWFilterBindingDelete; - virNWFilterBindingRef; virNWFilterBindingFree; - virNWFilterBindingGetPortDev; virNWFilterBindingGetFilterName; + virNWFilterBindingGetPortDev; + virNWFilterBindingGetXMLDesc; + virNWFilterBindingLookupByPortDev; + virNWFilterBindingRef; + virNodeGetSEVInfo; } LIBVIRT_4.4.0; LIBVIRT_4.10.0 { @@ -821,18 +818,18 @@ LIBVIRT_5.2.0 { LIBVIRT_5.5.0 { virNetworkListAllPorts; - virNetworkPortLookupByUUID; - virNetworkPortLookupByUUIDString; virNetworkPortCreateXML; + virNetworkPortDelete; + virNetworkPortFree; virNetworkPortGetNetwork; virNetworkPortGetParameters; - virNetworkPortGetXMLDesc; virNetworkPortGetUUID; virNetworkPortGetUUIDString; - virNetworkPortDelete; - virNetworkPortFree; + virNetworkPortGetXMLDesc; + virNetworkPortLookupByUUID; + virNetworkPortLookupByUUIDString; virNetworkPortRef; virNetworkPortSetParameters; } LIBVIRT_5.2.0; -# .... define new API here using predicted next version number .... +# .... define new API in sorted order using predicted next version number .... -- 2.20.1